feat: add debug-mode enhanced error handling for PostgreSQL transaction failures

[pyramation]

feat: add debug-mode enhanced error handling for PostgreSQL transaction failures

Summary

This PR adds comprehensive debug-mode error handling enhancements to help developers troubleshoot PostgreSQL transaction failures, particularly the common "current transaction is aborted" (error code 25P02) scenario. All enhancements are only active when LAUNCHQL_DEBUG=true or NODE_ENV=development to avoid any performance impact in production.

Key changes:

• New MigrationError utility class for contextual error information
• Enhanced executeQuery and withTransaction with debug context and better 25P02 handling
• Improved stored procedure error messages with change/project context
• Debug schema enhancements for error tracking in the database
• Enhanced deployment error handling with detailed context across all layers

Review & Testing Checklist for Human

• Test PostgreSQL transaction abort scenario - Verify that when a transaction fails with error 25P02, the enhanced error messages provide useful debugging context (change name, project, SQL query, params)
• Verify debug mode detection - Confirm that process.env.LAUNCHQL_DEBUG === 'true' || process.env.NODE_ENV === 'development' logic works correctly and consistently across all modified files
• Performance impact verification - Test that production builds (without debug flags) show no performance degradation and don't execute the debug-only code paths
• Database schema changes - Test that the debug schema enhancements in debug-schema.sql apply correctly and the debug_mode_enabled table is created properly
• Error context usefulness - Manually trigger some deployment/migration failures and verify the enhanced error messages actually help with debugging

Recommended test plan:

1. Set up environment with LAUNCHQL_DEBUG=true
2. Trigger a deployment that causes a PostgreSQL transaction failure
3. Verify enhanced error messages appear with change/project context
4. Test without debug flags to ensure normal error handling still works
5. Check database for debug schema enhancements

---

Diagram

%%{ init : { "theme" : "default" }}%%
graph TD
    Client["packages/core/src/migrate/client.ts"]:::major-edit
    Transaction["packages/core/src/migrate/utils/transaction.ts"]:::major-edit
    Deploy["packages/core/src/projects/deploy.ts"]:::major-edit
    Procedures["packages/core/src/migrate/sql/procedures.sql"]:::major-edit
    Errors["packages/core/src/migrate/utils/errors.ts"]:::major-edit
    DebugSchema["packages/core/src/migrate/sql/debug-schema.sql"]:::major-edit
    Index["packages/core/src/index.ts"]:::minor-edit
    
    Client -->|"uses"| Transaction
    Client -->|"uses"| Errors
    Deploy -->|"uses"| Client
    Transaction -->|"executes"| Procedures
    Client -->|"applies"| DebugSchema
    Index -->|"exports"| Errors
    
    subgraph Legend
        L1[Major Edit]:::major-edit
        L2[Minor Edit]:::minor-edit
        L3[Context/No Edit]:::context
    end

classDef major-edit fill:#90EE90
classDef minor-edit fill:#87CEEB
classDef context fill:#FFFFFF

Loading

Notes

• All debug enhancements are guarded by process.env.LAUNCHQL_DEBUG === 'true' || process.env.NODE_ENV === 'development'
• The MigrationError class provides structured error context including change names, project names, SQL queries, and error codes
• PostgreSQL error code 25P02 (transaction aborted) gets special handling with enhanced context
• Database schema is conditionally enhanced with error tracking columns only in debug mode
• Important: This code hasn't been fully tested locally due to PostgreSQL environment setup issues, so thorough testing is critical

Session info: Requested by Dan Lynch (@pyramation) - Devin session

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring