sqlew 3.6.10 → 3.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +318 -0
- package/README.md +54 -39
- package/assets/config.example.toml +93 -0
- package/assets/kanban-visualizer.png +0 -0
- package/assets/sample-agents/sqlew-architect.md +32 -13
- package/assets/sample-agents/sqlew-researcher.md +70 -17
- package/assets/sample-agents/sqlew-scrum-master.md +60 -25
- package/assets/schema.sql +2 -2
- package/dist/adapters/auth/auth-factory.d.ts +86 -0
- package/dist/adapters/auth/auth-factory.d.ts.map +1 -0
- package/dist/adapters/auth/auth-factory.js +103 -0
- package/dist/adapters/auth/auth-factory.js.map +1 -0
- package/dist/adapters/auth/auth-types.d.ts +30 -0
- package/dist/adapters/auth/auth-types.d.ts.map +1 -0
- package/dist/adapters/auth/auth-types.js +30 -0
- package/dist/adapters/auth/auth-types.js.map +1 -0
- package/dist/adapters/auth/base-auth-provider.d.ts +327 -0
- package/dist/adapters/auth/base-auth-provider.d.ts.map +1 -0
- package/dist/adapters/auth/base-auth-provider.js +111 -0
- package/dist/adapters/auth/base-auth-provider.js.map +1 -0
- package/dist/adapters/auth/direct-auth-provider.d.ts +356 -0
- package/dist/adapters/auth/direct-auth-provider.d.ts.map +1 -0
- package/dist/adapters/auth/direct-auth-provider.js +406 -0
- package/dist/adapters/auth/direct-auth-provider.js.map +1 -0
- package/dist/adapters/base-adapter.d.ts +638 -0
- package/dist/adapters/base-adapter.d.ts.map +1 -0
- package/dist/adapters/base-adapter.js +557 -0
- package/dist/adapters/base-adapter.js.map +1 -0
- package/dist/adapters/index.d.ts +13 -2
- package/dist/adapters/index.d.ts.map +1 -1
- package/dist/adapters/index.js +27 -5
- package/dist/adapters/index.js.map +1 -1
- package/dist/adapters/mysql-adapter.d.ts +547 -6
- package/dist/adapters/mysql-adapter.d.ts.map +1 -1
- package/dist/adapters/mysql-adapter.js +651 -32
- package/dist/adapters/mysql-adapter.js.map +1 -1
- package/dist/adapters/postgresql-adapter.d.ts +15 -4
- package/dist/adapters/postgresql-adapter.d.ts.map +1 -1
- package/dist/adapters/postgresql-adapter.js +19 -2
- package/dist/adapters/postgresql-adapter.js.map +1 -1
- package/dist/adapters/sqlite-adapter.d.ts +35 -5
- package/dist/adapters/sqlite-adapter.d.ts.map +1 -1
- package/dist/adapters/sqlite-adapter.js +57 -18
- package/dist/adapters/sqlite-adapter.js.map +1 -1
- package/dist/cli/db-dump.d.ts +32 -0
- package/dist/cli/db-dump.d.ts.map +1 -0
- package/dist/cli/db-dump.js +409 -0
- package/dist/cli/db-dump.js.map +1 -0
- package/dist/cli.js +24 -14
- package/dist/cli.js.map +1 -1
- package/dist/config/knex/bootstrap/20251025020452_create_master_tables.d.ts.map +1 -0
- package/dist/{migrations → config}/knex/bootstrap/20251025020452_create_master_tables.js +7 -2
- package/dist/config/knex/bootstrap/20251025020452_create_master_tables.js.map +1 -0
- package/dist/config/knex/bootstrap/20251025021152_create_transaction_tables.d.ts.map +1 -0
- package/dist/{migrations → config}/knex/bootstrap/20251025021152_create_transaction_tables.js +49 -50
- package/dist/config/knex/bootstrap/20251025021152_create_transaction_tables.js.map +1 -0
- package/dist/config/knex/bootstrap/20251025021351_create_indexes.d.ts.map +1 -0
- package/dist/config/knex/bootstrap/20251025021351_create_indexes.js.map +1 -0
- package/dist/config/knex/bootstrap/20251025021416_seed_master_data.d.ts.map +1 -0
- package/dist/{migrations → config}/knex/bootstrap/20251025021416_seed_master_data.js +11 -6
- package/dist/config/knex/bootstrap/20251025021416_seed_master_data.js.map +1 -0
- package/dist/config/knex/bootstrap/20251025070349_create_views.d.ts.map +1 -0
- package/dist/{migrations → config}/knex/bootstrap/20251025070349_create_views.js +66 -14
- package/dist/config/knex/bootstrap/20251025070349_create_views.js.map +1 -0
- package/dist/config/knex/enhancements/20251025081221_add_link_type_to_task_decision_links.d.ts.map +1 -0
- package/dist/config/knex/enhancements/20251025081221_add_link_type_to_task_decision_links.js +22 -0
- package/dist/config/knex/enhancements/20251025081221_add_link_type_to_task_decision_links.js.map +1 -0
- package/dist/config/knex/enhancements/20251025082220_fix_task_dependencies_columns.d.ts.map +1 -0
- package/dist/config/knex/enhancements/20251025082220_fix_task_dependencies_columns.js.map +1 -0
- package/dist/config/knex/enhancements/20251025090000_create_help_system_tables.d.ts.map +1 -0
- package/dist/{migrations → config}/knex/enhancements/20251025090000_create_help_system_tables.js +6 -0
- package/dist/config/knex/enhancements/20251025090000_create_help_system_tables.js.map +1 -0
- package/dist/config/knex/enhancements/20251025090100_seed_help_categories_and_use_cases.d.ts.map +1 -0
- package/dist/{migrations → config}/knex/enhancements/20251025090100_seed_help_categories_and_use_cases.js +6 -0
- package/dist/config/knex/enhancements/20251025090100_seed_help_categories_and_use_cases.js.map +1 -0
- package/dist/config/knex/enhancements/20251025100000_seed_help_metadata.d.ts.map +1 -0
- package/dist/{migrations → config}/knex/enhancements/20251025100000_seed_help_metadata.js +6 -0
- package/dist/config/knex/enhancements/20251025100000_seed_help_metadata.js.map +1 -0
- package/dist/config/knex/enhancements/20251025100100_seed_remaining_use_cases.d.ts.map +1 -0
- package/dist/config/knex/enhancements/20251025100100_seed_remaining_use_cases.js.map +1 -0
- package/dist/config/knex/enhancements/20251025120000_add_cascade_to_task_dependencies.d.ts.map +1 -0
- package/dist/{migrations → config}/knex/enhancements/20251025120000_add_cascade_to_task_dependencies.js +7 -0
- package/dist/config/knex/enhancements/20251025120000_add_cascade_to_task_dependencies.js.map +1 -0
- package/dist/config/knex/enhancements/20251027000000_add_agent_reuse_system.d.ts.map +1 -0
- package/dist/config/knex/enhancements/20251027000000_add_agent_reuse_system.js +62 -0
- package/dist/config/knex/enhancements/20251027000000_add_agent_reuse_system.js.map +1 -0
- package/dist/config/knex/enhancements/20251027010000_add_task_constraint_to_decision_context.d.ts.map +1 -0
- package/dist/config/knex/enhancements/20251027010000_add_task_constraint_to_decision_context.js.map +1 -0
- package/dist/config/knex/enhancements/20251027020000_update_agent_reusability.d.ts.map +1 -0
- package/dist/{migrations → config}/knex/enhancements/20251027020000_update_agent_reusability.js +6 -0
- package/dist/config/knex/enhancements/20251027020000_update_agent_reusability.js.map +1 -0
- package/dist/config/knex/enhancements/20251028000000_simplify_agent_system.d.ts.map +1 -0
- package/dist/{migrations → config}/knex/enhancements/20251028000000_simplify_agent_system.js +6 -0
- package/dist/config/knex/enhancements/20251028000000_simplify_agent_system.js.map +1 -0
- package/dist/config/knex/enhancements/20251031000000_drop_orphaned_message_view.d.ts +13 -0
- package/dist/config/knex/enhancements/20251031000000_drop_orphaned_message_view.d.ts.map +1 -0
- package/dist/config/knex/enhancements/20251031000000_drop_orphaned_message_view.js +48 -0
- package/dist/config/knex/enhancements/20251031000000_drop_orphaned_message_view.js.map +1 -0
- package/dist/config/knex/enhancements/20251104000003_rename_constraints_created_by_to_agent_id.d.ts +24 -0
- package/dist/config/knex/enhancements/20251104000003_rename_constraints_created_by_to_agent_id.d.ts.map +1 -0
- package/dist/config/knex/enhancements/20251104000003_rename_constraints_created_by_to_agent_id.js +189 -0
- package/dist/config/knex/enhancements/20251104000003_rename_constraints_created_by_to_agent_id.js.map +1 -0
- package/dist/config/knex/enhancements/20251105000000_add_token_usage_table.d.ts +16 -0
- package/dist/config/knex/enhancements/20251105000000_add_token_usage_table.d.ts.map +1 -0
- package/dist/config/knex/enhancements/20251105000000_add_token_usage_table.js +65 -0
- package/dist/config/knex/enhancements/20251105000000_add_token_usage_table.js.map +1 -0
- package/dist/config/knex/enhancements/20251105000001_rename_decision_context_decided_by_to_agent_id.d.ts +23 -0
- package/dist/config/knex/enhancements/20251105000001_rename_decision_context_decided_by_to_agent_id.d.ts.map +1 -0
- package/dist/config/knex/enhancements/20251105000001_rename_decision_context_decided_by_to_agent_id.js +118 -0
- package/dist/config/knex/enhancements/20251105000001_rename_decision_context_decided_by_to_agent_id.js.map +1 -0
- package/dist/config/knex/upgrades/20251024010000_upgrade_v1_0_to_v1_1.d.ts.map +1 -0
- package/dist/config/knex/upgrades/20251024010000_upgrade_v1_0_to_v1_1.js.map +1 -0
- package/dist/config/knex/upgrades/20251024020000_upgrade_v2_0_to_v2_1.d.ts.map +1 -0
- package/dist/config/knex/upgrades/20251024020000_upgrade_v2_0_to_v2_1.js.map +1 -0
- package/dist/config/knex/upgrades/20251024030000_upgrade_v2_1_to_v3_0.d.ts.map +1 -0
- package/dist/config/knex/upgrades/20251024030000_upgrade_v2_1_to_v3_0.js.map +1 -0
- package/dist/config/knex/upgrades/20251024040000_upgrade_v3_0_to_v3_2.d.ts.map +1 -0
- package/dist/config/knex/upgrades/20251024040000_upgrade_v3_0_to_v3_2.js.map +1 -0
- package/dist/config/knex/upgrades/20251024050000_upgrade_v3_2_0_to_v3_2_2.d.ts.map +1 -0
- package/dist/config/knex/upgrades/20251024050000_upgrade_v3_2_0_to_v3_2_2.js.map +1 -0
- package/dist/config/knex/upgrades/20251024060000_upgrade_v3_4_to_v3_5.d.ts.map +1 -0
- package/dist/config/knex/upgrades/20251024060000_upgrade_v3_4_to_v3_5.js.map +1 -0
- package/dist/config/knex/upgrades/20251024070000_upgrade_v3_5_to_v3_6.d.ts.map +1 -0
- package/dist/config/knex/upgrades/20251024070000_upgrade_v3_5_to_v3_6.js.map +1 -0
- package/dist/config/knex/upgrades/20251104000000_add_multi_project_v3_7_0.d.ts +49 -0
- package/dist/config/knex/upgrades/20251104000000_add_multi_project_v3_7_0.d.ts.map +1 -0
- package/dist/config/knex/upgrades/20251104000000_add_multi_project_v3_7_0.js +864 -0
- package/dist/config/knex/upgrades/20251104000000_add_multi_project_v3_7_0.js.map +1 -0
- package/dist/config/loader.d.ts +19 -1
- package/dist/config/loader.d.ts.map +1 -1
- package/dist/config/loader.js +149 -4
- package/dist/config/loader.js.map +1 -1
- package/dist/config/types.d.ts +261 -2
- package/dist/config/types.d.ts.map +1 -1
- package/dist/config/types.js.map +1 -1
- package/dist/config/writer.d.ts +65 -0
- package/dist/config/writer.d.ts.map +1 -0
- package/dist/config/writer.js +139 -0
- package/dist/config/writer.js.map +1 -0
- package/dist/database.d.ts +11 -2
- package/dist/database.d.ts.map +1 -1
- package/dist/database.js +62 -6
- package/dist/database.js.map +1 -1
- package/dist/index.js +165 -35
- package/dist/index.js.map +1 -1
- package/dist/knexfile.d.ts.map +1 -1
- package/dist/knexfile.js +88 -12
- package/dist/knexfile.js.map +1 -1
- package/dist/tests/all-features.test.js +15 -3
- package/dist/tests/all-features.test.js.map +1 -1
- package/dist/tests/config-loader.test.d.ts +6 -0
- package/dist/tests/config-loader.test.d.ts.map +1 -0
- package/dist/tests/config-loader.test.js +201 -0
- package/dist/tests/config-loader.test.js.map +1 -0
- package/dist/tests/connection-manager-integration.test.d.ts +2 -0
- package/dist/tests/connection-manager-integration.test.d.ts.map +1 -0
- package/dist/tests/connection-manager-integration.test.js +431 -0
- package/dist/tests/connection-manager-integration.test.js.map +1 -0
- package/dist/tests/connection-manager.test.d.ts +2 -0
- package/dist/tests/connection-manager.test.d.ts.map +1 -0
- package/dist/tests/connection-manager.test.js +361 -0
- package/dist/tests/connection-manager.test.js.map +1 -0
- package/dist/tests/dump-import.test.d.ts +15 -0
- package/dist/tests/dump-import.test.d.ts.map +1 -0
- package/dist/tests/dump-import.test.js +430 -0
- package/dist/tests/dump-import.test.js.map +1 -0
- package/dist/tests/migration-idempotency.test.d.ts +2 -0
- package/dist/tests/migration-idempotency.test.d.ts.map +1 -0
- package/dist/tests/migration-idempotency.test.js +330 -0
- package/dist/tests/migration-idempotency.test.js.map +1 -0
- package/dist/tests/migration-upgrade-paths.test.d.ts +2 -0
- package/dist/tests/migration-upgrade-paths.test.d.ts.map +1 -0
- package/dist/tests/migration-upgrade-paths.test.js +248 -0
- package/dist/tests/migration-upgrade-paths.test.js.map +1 -0
- package/dist/tests/multi-project-migration.test.d.ts +17 -0
- package/dist/tests/multi-project-migration.test.d.ts.map +1 -0
- package/dist/tests/multi-project-migration.test.js +399 -0
- package/dist/tests/multi-project-migration.test.js.map +1 -0
- package/dist/tests/multi-project.test.d.ts +5 -0
- package/dist/tests/multi-project.test.d.ts.map +1 -0
- package/dist/tests/multi-project.test.js +238 -0
- package/dist/tests/multi-project.test.js.map +1 -0
- package/dist/tests/schema-migration.test.d.ts +8 -0
- package/dist/tests/schema-migration.test.d.ts.map +1 -0
- package/dist/tests/schema-migration.test.js +108 -0
- package/dist/tests/schema-migration.test.js.map +1 -0
- package/dist/tests/sql-dump-converters.test.d.ts +7 -0
- package/dist/tests/sql-dump-converters.test.d.ts.map +1 -0
- package/dist/tests/sql-dump-converters.test.js +314 -0
- package/dist/tests/sql-dump-converters.test.js.map +1 -0
- package/dist/tests/sql-dump-cross-database.test.d.ts +21 -0
- package/dist/tests/sql-dump-cross-database.test.d.ts.map +1 -0
- package/dist/tests/sql-dump-cross-database.test.js +314 -0
- package/dist/tests/sql-dump-cross-database.test.js.map +1 -0
- package/dist/tests/sql-dump-default-conversions.test.d.ts +8 -0
- package/dist/tests/sql-dump-default-conversions.test.d.ts.map +1 -0
- package/dist/tests/sql-dump-default-conversions.test.js +141 -0
- package/dist/tests/sql-dump-default-conversions.test.js.map +1 -0
- package/dist/tests/sql-dump-fk-constraints.test.d.ts +13 -0
- package/dist/tests/sql-dump-fk-constraints.test.d.ts.map +1 -0
- package/dist/tests/sql-dump-fk-constraints.test.js +381 -0
- package/dist/tests/sql-dump-fk-constraints.test.js.map +1 -0
- package/dist/tests/sql-dump-indexes.test.d.ts +12 -0
- package/dist/tests/sql-dump-indexes.test.d.ts.map +1 -0
- package/dist/tests/sql-dump-indexes.test.js +269 -0
- package/dist/tests/sql-dump-indexes.test.js.map +1 -0
- package/dist/tests/sql-dump-integration.test.d.ts +16 -0
- package/dist/tests/sql-dump-integration.test.d.ts.map +1 -0
- package/dist/tests/sql-dump-integration.test.js +342 -0
- package/dist/tests/sql-dump-integration.test.js.map +1 -0
- package/dist/tests/sql-dump-table-ordering.test.d.ts +8 -0
- package/dist/tests/sql-dump-table-ordering.test.d.ts.map +1 -0
- package/dist/tests/sql-dump-table-ordering.test.js +253 -0
- package/dist/tests/sql-dump-table-ordering.test.js.map +1 -0
- package/dist/tests/tasks.link-file-backward-compat.test.js +11 -1
- package/dist/tests/tasks.link-file-backward-compat.test.js.map +1 -1
- package/dist/tests/tasks.watch-files-action.test.js +11 -1
- package/dist/tests/tasks.watch-files-action.test.js.map +1 -1
- package/dist/tests/type-conversion.test.d.ts +8 -0
- package/dist/tests/type-conversion.test.d.ts.map +1 -0
- package/dist/tests/type-conversion.test.js +312 -0
- package/dist/tests/type-conversion.test.js.map +1 -0
- package/dist/tests/utils/test-helpers.d.ts +93 -0
- package/dist/tests/utils/test-helpers.d.ts.map +1 -0
- package/dist/tests/utils/test-helpers.js +407 -0
- package/dist/tests/utils/test-helpers.js.map +1 -0
- package/dist/tools/config.d.ts +58 -0
- package/dist/tools/config.d.ts.map +1 -0
- package/dist/tools/config.js +281 -0
- package/dist/tools/config.js.map +1 -0
- package/dist/tools/constraints.d.ts.map +1 -1
- package/dist/tools/constraints.js +138 -122
- package/dist/tools/constraints.js.map +1 -1
- package/dist/tools/context.d.ts.map +1 -1
- package/dist/tools/context.js +216 -109
- package/dist/tools/context.js.map +1 -1
- package/dist/tools/files.d.ts.map +1 -1
- package/dist/tools/files.js +123 -102
- package/dist/tools/files.js.map +1 -1
- package/dist/tools/tasks.d.ts.map +1 -1
- package/dist/tools/tasks.js +581 -518
- package/dist/tools/tasks.js.map +1 -1
- package/dist/tools/utils.d.ts +5 -0
- package/dist/tools/utils.d.ts.map +1 -1
- package/dist/tools/utils.js +176 -122
- package/dist/tools/utils.js.map +1 -1
- package/dist/types.d.ts +9 -26
- package/dist/types.d.ts.map +1 -1
- package/dist/utils/cleanup.d.ts +3 -0
- package/dist/utils/cleanup.d.ts.map +1 -1
- package/dist/utils/cleanup.js +14 -2
- package/dist/utils/cleanup.js.map +1 -1
- package/dist/utils/connection-manager.d.ts +59 -0
- package/dist/utils/connection-manager.d.ts.map +1 -0
- package/dist/utils/connection-manager.js +178 -0
- package/dist/utils/connection-manager.js.map +1 -0
- package/dist/utils/debug-logger.d.ts +8 -4
- package/dist/utils/debug-logger.d.ts.map +1 -1
- package/dist/utils/debug-logger.js +27 -7
- package/dist/utils/debug-logger.js.map +1 -1
- package/dist/utils/error-handler.d.ts +2 -2
- package/dist/utils/error-handler.d.ts.map +1 -1
- package/dist/utils/error-handler.js +10 -7
- package/dist/utils/error-handler.js.map +1 -1
- package/dist/utils/parameter-validator.d.ts.map +1 -1
- package/dist/utils/parameter-validator.js +36 -15
- package/dist/utils/parameter-validator.js.map +1 -1
- package/dist/utils/project-context.d.ts +111 -0
- package/dist/utils/project-context.d.ts.map +1 -0
- package/dist/utils/project-context.js +187 -0
- package/dist/utils/project-context.js.map +1 -0
- package/dist/utils/sql-dump-converters.d.ts +188 -0
- package/dist/utils/sql-dump-converters.d.ts.map +1 -0
- package/dist/utils/sql-dump-converters.js +311 -0
- package/dist/utils/sql-dump-converters.js.map +1 -0
- package/dist/utils/sql-dump.d.ts +102 -0
- package/dist/utils/sql-dump.d.ts.map +1 -0
- package/dist/utils/sql-dump.js +1550 -0
- package/dist/utils/sql-dump.js.map +1 -0
- package/dist/utils/vcs-adapter.d.ts +42 -0
- package/dist/utils/vcs-adapter.d.ts.map +1 -1
- package/dist/utils/vcs-adapter.js +154 -0
- package/dist/utils/vcs-adapter.js.map +1 -1
- package/docs/BASEADAPTER_IMPLEMENTATION.md +399 -0
- package/docs/DATABASE_AUTH.md +445 -0
- package/docs/DATABASE_MIGRATION.md +247 -0
- package/docs/MULTI_PROJECT_ARCHITECTURE.md +497 -0
- package/package.json +12 -4
- package/dist/migrations/knex/bootstrap/20251025020452_create_master_tables.d.ts.map +0 -1
- package/dist/migrations/knex/bootstrap/20251025020452_create_master_tables.js.map +0 -1
- package/dist/migrations/knex/bootstrap/20251025021152_create_transaction_tables.d.ts.map +0 -1
- package/dist/migrations/knex/bootstrap/20251025021152_create_transaction_tables.js.map +0 -1
- package/dist/migrations/knex/bootstrap/20251025021351_create_indexes.d.ts.map +0 -1
- package/dist/migrations/knex/bootstrap/20251025021351_create_indexes.js.map +0 -1
- package/dist/migrations/knex/bootstrap/20251025021416_seed_master_data.d.ts.map +0 -1
- package/dist/migrations/knex/bootstrap/20251025021416_seed_master_data.js.map +0 -1
- package/dist/migrations/knex/bootstrap/20251025070349_create_views.d.ts.map +0 -1
- package/dist/migrations/knex/bootstrap/20251025070349_create_views.js.map +0 -1
- package/dist/migrations/knex/enhancements/20251025081221_add_link_type_to_task_decision_links.d.ts.map +0 -1
- package/dist/migrations/knex/enhancements/20251025081221_add_link_type_to_task_decision_links.js +0 -15
- package/dist/migrations/knex/enhancements/20251025081221_add_link_type_to_task_decision_links.js.map +0 -1
- package/dist/migrations/knex/enhancements/20251025082220_fix_task_dependencies_columns.d.ts.map +0 -1
- package/dist/migrations/knex/enhancements/20251025082220_fix_task_dependencies_columns.js.map +0 -1
- package/dist/migrations/knex/enhancements/20251025090000_create_help_system_tables.d.ts.map +0 -1
- package/dist/migrations/knex/enhancements/20251025090000_create_help_system_tables.js.map +0 -1
- package/dist/migrations/knex/enhancements/20251025090100_seed_help_categories_and_use_cases.d.ts.map +0 -1
- package/dist/migrations/knex/enhancements/20251025090100_seed_help_categories_and_use_cases.js.map +0 -1
- package/dist/migrations/knex/enhancements/20251025100000_seed_help_metadata.d.ts.map +0 -1
- package/dist/migrations/knex/enhancements/20251025100000_seed_help_metadata.js.map +0 -1
- package/dist/migrations/knex/enhancements/20251025100100_seed_remaining_use_cases.d.ts.map +0 -1
- package/dist/migrations/knex/enhancements/20251025100100_seed_remaining_use_cases.js.map +0 -1
- package/dist/migrations/knex/enhancements/20251025120000_add_cascade_to_task_dependencies.d.ts.map +0 -1
- package/dist/migrations/knex/enhancements/20251025120000_add_cascade_to_task_dependencies.js.map +0 -1
- package/dist/migrations/knex/enhancements/20251027000000_add_agent_reuse_system.d.ts.map +0 -1
- package/dist/migrations/knex/enhancements/20251027000000_add_agent_reuse_system.js +0 -34
- package/dist/migrations/knex/enhancements/20251027000000_add_agent_reuse_system.js.map +0 -1
- package/dist/migrations/knex/enhancements/20251027010000_add_task_constraint_to_decision_context.d.ts.map +0 -1
- package/dist/migrations/knex/enhancements/20251027010000_add_task_constraint_to_decision_context.js.map +0 -1
- package/dist/migrations/knex/enhancements/20251027020000_update_agent_reusability.d.ts.map +0 -1
- package/dist/migrations/knex/enhancements/20251027020000_update_agent_reusability.js.map +0 -1
- package/dist/migrations/knex/enhancements/20251028000000_simplify_agent_system.d.ts.map +0 -1
- package/dist/migrations/knex/enhancements/20251028000000_simplify_agent_system.js.map +0 -1
- package/dist/migrations/knex/upgrades/20251024010000_upgrade_v1_0_to_v1_1.d.ts.map +0 -1
- package/dist/migrations/knex/upgrades/20251024010000_upgrade_v1_0_to_v1_1.js.map +0 -1
- package/dist/migrations/knex/upgrades/20251024020000_upgrade_v2_0_to_v2_1.d.ts.map +0 -1
- package/dist/migrations/knex/upgrades/20251024020000_upgrade_v2_0_to_v2_1.js.map +0 -1
- package/dist/migrations/knex/upgrades/20251024030000_upgrade_v2_1_to_v3_0.d.ts.map +0 -1
- package/dist/migrations/knex/upgrades/20251024030000_upgrade_v2_1_to_v3_0.js.map +0 -1
- package/dist/migrations/knex/upgrades/20251024040000_upgrade_v3_0_to_v3_2.d.ts.map +0 -1
- package/dist/migrations/knex/upgrades/20251024040000_upgrade_v3_0_to_v3_2.js.map +0 -1
- package/dist/migrations/knex/upgrades/20251024050000_upgrade_v3_2_0_to_v3_2_2.d.ts.map +0 -1
- package/dist/migrations/knex/upgrades/20251024050000_upgrade_v3_2_0_to_v3_2_2.js.map +0 -1
- package/dist/migrations/knex/upgrades/20251024060000_upgrade_v3_4_to_v3_5.d.ts.map +0 -1
- package/dist/migrations/knex/upgrades/20251024060000_upgrade_v3_4_to_v3_5.js.map +0 -1
- package/dist/migrations/knex/upgrades/20251024070000_upgrade_v3_5_to_v3_6.d.ts.map +0 -1
- package/dist/migrations/knex/upgrades/20251024070000_upgrade_v3_5_to_v3_6.js.map +0 -1
- /package/dist/{migrations → config}/knex/bootstrap/20251025020452_create_master_tables.d.ts +0 -0
- /package/dist/{migrations → config}/knex/bootstrap/20251025021152_create_transaction_tables.d.ts +0 -0
- /package/dist/{migrations → config}/knex/bootstrap/20251025021351_create_indexes.d.ts +0 -0
- /package/dist/{migrations → config}/knex/bootstrap/20251025021351_create_indexes.js +0 -0
- /package/dist/{migrations → config}/knex/bootstrap/20251025021416_seed_master_data.d.ts +0 -0
- /package/dist/{migrations → config}/knex/bootstrap/20251025070349_create_views.d.ts +0 -0
- /package/dist/{migrations → config}/knex/enhancements/20251025081221_add_link_type_to_task_decision_links.d.ts +0 -0
- /package/dist/{migrations → config}/knex/enhancements/20251025082220_fix_task_dependencies_columns.d.ts +0 -0
- /package/dist/{migrations → config}/knex/enhancements/20251025082220_fix_task_dependencies_columns.js +0 -0
- /package/dist/{migrations → config}/knex/enhancements/20251025090000_create_help_system_tables.d.ts +0 -0
- /package/dist/{migrations → config}/knex/enhancements/20251025090100_seed_help_categories_and_use_cases.d.ts +0 -0
- /package/dist/{migrations → config}/knex/enhancements/20251025100000_seed_help_metadata.d.ts +0 -0
- /package/dist/{migrations → config}/knex/enhancements/20251025100100_seed_remaining_use_cases.d.ts +0 -0
- /package/dist/{migrations → config}/knex/enhancements/20251025100100_seed_remaining_use_cases.js +0 -0
- /package/dist/{migrations → config}/knex/enhancements/20251025120000_add_cascade_to_task_dependencies.d.ts +0 -0
- /package/dist/{migrations → config}/knex/enhancements/20251027000000_add_agent_reuse_system.d.ts +0 -0
- /package/dist/{migrations → config}/knex/enhancements/20251027010000_add_task_constraint_to_decision_context.d.ts +0 -0
- /package/dist/{migrations → config}/knex/enhancements/20251027010000_add_task_constraint_to_decision_context.js +0 -0
- /package/dist/{migrations → config}/knex/enhancements/20251027020000_update_agent_reusability.d.ts +0 -0
- /package/dist/{migrations → config}/knex/enhancements/20251028000000_simplify_agent_system.d.ts +0 -0
- /package/dist/{migrations → config}/knex/upgrades/20251024010000_upgrade_v1_0_to_v1_1.d.ts +0 -0
- /package/dist/{migrations → config}/knex/upgrades/20251024010000_upgrade_v1_0_to_v1_1.js +0 -0
- /package/dist/{migrations → config}/knex/upgrades/20251024020000_upgrade_v2_0_to_v2_1.d.ts +0 -0
- /package/dist/{migrations → config}/knex/upgrades/20251024020000_upgrade_v2_0_to_v2_1.js +0 -0
- /package/dist/{migrations → config}/knex/upgrades/20251024030000_upgrade_v2_1_to_v3_0.d.ts +0 -0
- /package/dist/{migrations → config}/knex/upgrades/20251024030000_upgrade_v2_1_to_v3_0.js +0 -0
- /package/dist/{migrations → config}/knex/upgrades/20251024040000_upgrade_v3_0_to_v3_2.d.ts +0 -0
- /package/dist/{migrations → config}/knex/upgrades/20251024040000_upgrade_v3_0_to_v3_2.js +0 -0
- /package/dist/{migrations → config}/knex/upgrades/20251024050000_upgrade_v3_2_0_to_v3_2_2.d.ts +0 -0
- /package/dist/{migrations → config}/knex/upgrades/20251024050000_upgrade_v3_2_0_to_v3_2_2.js +0 -0
- /package/dist/{migrations → config}/knex/upgrades/20251024060000_upgrade_v3_4_to_v3_5.d.ts +0 -0
- /package/dist/{migrations → config}/knex/upgrades/20251024060000_upgrade_v3_4_to_v3_5.js +0 -0
- /package/dist/{migrations → config}/knex/upgrades/20251024070000_upgrade_v3_5_to_v3_6.d.ts +0 -0
- /package/dist/{migrations → config}/knex/upgrades/20251024070000_upgrade_v3_5_to_v3_6.js +0 -0
|
@@ -0,0 +1,638 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Base adapter for database connections with authentication integration.
|
|
3
|
+
*
|
|
4
|
+
* This module provides the foundation for all database adapters in the multi-RDBMS system.
|
|
5
|
+
* It integrates authentication providers (SSH tunneling, direct connections, cloud IAM) with
|
|
6
|
+
* Knex.js-based database connections, managing the complete connection lifecycle.
|
|
7
|
+
*
|
|
8
|
+
* **Key Responsibilities:**
|
|
9
|
+
* - Authentication provider integration via factory
|
|
10
|
+
* - Connection lifecycle management (connect → authenticate → establish → cleanup)
|
|
11
|
+
* - Knex.js instance management and access control
|
|
12
|
+
* - Transaction support delegation
|
|
13
|
+
* - Abstract methods for adapter-specific initialization
|
|
14
|
+
*
|
|
15
|
+
* **Connection Flow:**
|
|
16
|
+
* 1. Constructor: Initialize with DatabaseConfig
|
|
17
|
+
* 2. connect(): Authenticate via provider, establish Knex connection
|
|
18
|
+
* 3. initialize(): Adapter-specific setup (pragmas, schemas, etc.)
|
|
19
|
+
* 4. getKnex(): Access Knex instance for queries
|
|
20
|
+
* 5. disconnect(): Close Knex connection
|
|
21
|
+
* 6. cleanup(): Release authentication resources (tunnels, tokens)
|
|
22
|
+
*
|
|
23
|
+
* **Architecture:**
|
|
24
|
+
* ```
|
|
25
|
+
* BaseAdapter (abstract)
|
|
26
|
+
* ├── Authentication Layer: BaseAuthProvider integration
|
|
27
|
+
* ├── Connection Layer: Knex.js management
|
|
28
|
+
* └── Adapter-Specific: Abstract methods for subclasses
|
|
29
|
+
*
|
|
30
|
+
* Concrete Adapters:
|
|
31
|
+
* ├── SQLiteAdapter (no auth required)
|
|
32
|
+
* ├── PostgreSQLAdapter (with auth integration)
|
|
33
|
+
* └── MySQLAdapter (with auth integration)
|
|
34
|
+
* ```
|
|
35
|
+
*
|
|
36
|
+
* @module adapters/base-adapter
|
|
37
|
+
* @since v3.7.0
|
|
38
|
+
*/
|
|
39
|
+
import type { Knex } from 'knex';
|
|
40
|
+
import type { DatabaseAdapter } from './types.js';
|
|
41
|
+
import type { DatabaseConfig } from '../config/types.js';
|
|
42
|
+
import type { BaseAuthProvider, ConnectionParams } from './auth/base-auth-provider.js';
|
|
43
|
+
/**
|
|
44
|
+
* Abstract base class for database adapters with authentication integration.
|
|
45
|
+
*
|
|
46
|
+
* This class provides common functionality for all database adapters, integrating
|
|
47
|
+
* authentication providers with Knex.js connections. Subclasses implement
|
|
48
|
+
* database-specific features (SQLite pragmas, PostgreSQL settings, MySQL config).
|
|
49
|
+
*
|
|
50
|
+
* **Design Principles:**
|
|
51
|
+
* - Separation of concerns: Auth provider handles authentication, adapter handles DB operations
|
|
52
|
+
* - Lazy initialization: Knex instance created only after successful authentication
|
|
53
|
+
* - Resource safety: Explicit cleanup for both auth providers and DB connections
|
|
54
|
+
* - Fail-fast validation: Auth provider validates config before connection attempt
|
|
55
|
+
* - Backward compatibility: Maintains DatabaseAdapter interface contract
|
|
56
|
+
*
|
|
57
|
+
* **Authentication Integration:**
|
|
58
|
+
* - SQLite: No authentication provider (null), direct file connection
|
|
59
|
+
* - PostgreSQL/MySQL: Auth provider handles tunneling/IAM/direct auth
|
|
60
|
+
* - SSH tunneling: Provider establishes tunnel, returns localhost connection params
|
|
61
|
+
* - Cloud IAM: Provider generates temporary tokens, returns params with SSL config
|
|
62
|
+
*
|
|
63
|
+
* **Error Handling:**
|
|
64
|
+
* - Constructor: Config validation (throws if invalid)
|
|
65
|
+
* - connect(): Authentication failures, connection failures
|
|
66
|
+
* - getKnex(): Throws if called before connect()
|
|
67
|
+
* - cleanup(): Swallows errors to prevent cascading failures
|
|
68
|
+
*
|
|
69
|
+
* @abstract
|
|
70
|
+
* @implements {DatabaseAdapter}
|
|
71
|
+
*
|
|
72
|
+
* @example
|
|
73
|
+
* // Implementing a PostgreSQL adapter
|
|
74
|
+
* class PostgreSQLAdapter extends BaseAdapter {
|
|
75
|
+
* readonly supportsReturning = true;
|
|
76
|
+
* readonly supportsJSON = true;
|
|
77
|
+
* readonly databaseName = 'postgresql' as const;
|
|
78
|
+
*
|
|
79
|
+
* async initialize(): Promise<void> {
|
|
80
|
+
* const knex = this.getKnex();
|
|
81
|
+
* // PostgreSQL-specific initialization
|
|
82
|
+
* await knex.raw('SET statement_timeout = 30000');
|
|
83
|
+
* await knex.raw('SET timezone = "UTC"');
|
|
84
|
+
* }
|
|
85
|
+
*
|
|
86
|
+
* getDialect(): string {
|
|
87
|
+
* return 'pg';
|
|
88
|
+
* }
|
|
89
|
+
*
|
|
90
|
+
* // Implement other DatabaseAdapter methods...
|
|
91
|
+
* }
|
|
92
|
+
*
|
|
93
|
+
* @example
|
|
94
|
+
* // Using the adapter with authentication
|
|
95
|
+
* const config: DatabaseConfig = {
|
|
96
|
+
* type: 'postgres',
|
|
97
|
+
* connection: {
|
|
98
|
+
* host: 'db.internal',
|
|
99
|
+
* port: 5432,
|
|
100
|
+
* database: 'production'
|
|
101
|
+
* },
|
|
102
|
+
* auth: {
|
|
103
|
+
* type: 'ssh',
|
|
104
|
+
* user: 'postgres',
|
|
105
|
+
* password: 'secret',
|
|
106
|
+
* ssh: {
|
|
107
|
+
* host: 'bastion.example.com',
|
|
108
|
+
* username: 'deploy',
|
|
109
|
+
* privateKeyPath: '/path/to/key.pem'
|
|
110
|
+
* }
|
|
111
|
+
* }
|
|
112
|
+
* };
|
|
113
|
+
*
|
|
114
|
+
* const adapter = new PostgreSQLAdapter(config);
|
|
115
|
+
* try {
|
|
116
|
+
* await adapter.connect();
|
|
117
|
+
* const knex = adapter.getKnex();
|
|
118
|
+
* const users = await knex('users').select('*');
|
|
119
|
+
* console.log(users);
|
|
120
|
+
* } finally {
|
|
121
|
+
* await adapter.disconnect();
|
|
122
|
+
* await adapter.cleanup();
|
|
123
|
+
* }
|
|
124
|
+
*
|
|
125
|
+
* @example
|
|
126
|
+
* // Transaction support
|
|
127
|
+
* const adapter = new PostgreSQLAdapter(config);
|
|
128
|
+
* await adapter.connect();
|
|
129
|
+
*
|
|
130
|
+
* try {
|
|
131
|
+
* await adapter.transaction(async (trx) => {
|
|
132
|
+
* await trx('accounts').where({ id: 1 }).update({ balance: 100 });
|
|
133
|
+
* await trx('accounts').where({ id: 2 }).update({ balance: 200 });
|
|
134
|
+
* });
|
|
135
|
+
* } finally {
|
|
136
|
+
* await adapter.disconnect();
|
|
137
|
+
* await adapter.cleanup();
|
|
138
|
+
* }
|
|
139
|
+
*
|
|
140
|
+
* @example
|
|
141
|
+
* // SQLite adapter (no authentication)
|
|
142
|
+
* class SQLiteAdapter extends BaseAdapter {
|
|
143
|
+
* async connect(): Promise<Knex> {
|
|
144
|
+
* // SQLite doesn't need authentication provider
|
|
145
|
+
* // Override connect to bypass auth flow
|
|
146
|
+
* const config: Knex.Config = {
|
|
147
|
+
* client: 'better-sqlite3',
|
|
148
|
+
* connection: {
|
|
149
|
+
* filename: this.config.connection.database
|
|
150
|
+
* },
|
|
151
|
+
* useNullAsDefault: true
|
|
152
|
+
* };
|
|
153
|
+
*
|
|
154
|
+
* this.knex = knex(config);
|
|
155
|
+
* await this.initialize();
|
|
156
|
+
* return this.knex;
|
|
157
|
+
* }
|
|
158
|
+
*
|
|
159
|
+
* getDialect(): string {
|
|
160
|
+
* return 'sqlite3';
|
|
161
|
+
* }
|
|
162
|
+
* }
|
|
163
|
+
*/
|
|
164
|
+
export declare abstract class BaseAdapter implements DatabaseAdapter {
|
|
165
|
+
/**
|
|
166
|
+
* Database configuration containing connection and authentication settings.
|
|
167
|
+
* @protected
|
|
168
|
+
* @readonly
|
|
169
|
+
*/
|
|
170
|
+
protected readonly config: DatabaseConfig;
|
|
171
|
+
/**
|
|
172
|
+
* Authentication provider instance for handling credentials, tunnels, and tokens.
|
|
173
|
+
* Null for databases that don't require authentication (e.g., SQLite).
|
|
174
|
+
* @protected
|
|
175
|
+
*/
|
|
176
|
+
protected authProvider: BaseAuthProvider | null;
|
|
177
|
+
/**
|
|
178
|
+
* Knex.js instance for database operations.
|
|
179
|
+
* Null until connect() is called successfully.
|
|
180
|
+
* @protected
|
|
181
|
+
*/
|
|
182
|
+
protected knexInstance: Knex | null;
|
|
183
|
+
/**
|
|
184
|
+
* Creates a new database adapter instance.
|
|
185
|
+
*
|
|
186
|
+
* @param {DatabaseConfig} config - Database configuration object
|
|
187
|
+
*
|
|
188
|
+
* @throws {Error} If database type is unsupported
|
|
189
|
+
*
|
|
190
|
+
* @example
|
|
191
|
+
* const adapter = new PostgreSQLAdapter({
|
|
192
|
+
* type: 'postgres',
|
|
193
|
+
* connection: { host: 'localhost', port: 5432, database: 'mydb' },
|
|
194
|
+
* auth: { type: 'direct', user: 'postgres', password: 'postgres' }
|
|
195
|
+
* });
|
|
196
|
+
*/
|
|
197
|
+
constructor(config: DatabaseConfig);
|
|
198
|
+
/**
|
|
199
|
+
* Performs adapter-specific initialization after connection is established.
|
|
200
|
+
*
|
|
201
|
+
* This method is called automatically after Knex connection is created.
|
|
202
|
+
* Subclasses implement database-specific setup:
|
|
203
|
+
*
|
|
204
|
+
* **SQLite:**
|
|
205
|
+
* - PRAGMA settings (journal_mode, foreign_keys, synchronous)
|
|
206
|
+
* - Query performance optimizations
|
|
207
|
+
*
|
|
208
|
+
* **PostgreSQL:**
|
|
209
|
+
* - Session settings (statement_timeout, timezone)
|
|
210
|
+
* - Search path configuration
|
|
211
|
+
* - Connection pool settings
|
|
212
|
+
*
|
|
213
|
+
* **MySQL:**
|
|
214
|
+
* - Session variables (sql_mode, time_zone)
|
|
215
|
+
* - Character set configuration
|
|
216
|
+
* - Transaction isolation level
|
|
217
|
+
*
|
|
218
|
+
* @abstract
|
|
219
|
+
* @returns {Promise<void>}
|
|
220
|
+
*
|
|
221
|
+
* @throws {Error} If initialization fails
|
|
222
|
+
*
|
|
223
|
+
* @example
|
|
224
|
+
* // SQLite implementation
|
|
225
|
+
* async initialize(): Promise<void> {
|
|
226
|
+
* const knex = this.getKnex();
|
|
227
|
+
* await knex.raw('PRAGMA journal_mode = WAL');
|
|
228
|
+
* await knex.raw('PRAGMA foreign_keys = ON');
|
|
229
|
+
* await knex.raw('PRAGMA synchronous = NORMAL');
|
|
230
|
+
* }
|
|
231
|
+
*
|
|
232
|
+
* @example
|
|
233
|
+
* // PostgreSQL implementation
|
|
234
|
+
* async initialize(): Promise<void> {
|
|
235
|
+
* const knex = this.getKnex();
|
|
236
|
+
* await knex.raw('SET statement_timeout = 30000');
|
|
237
|
+
* await knex.raw('SET timezone = "UTC"');
|
|
238
|
+
* await knex.raw('SET search_path = public');
|
|
239
|
+
* }
|
|
240
|
+
*/
|
|
241
|
+
abstract initialize(): Promise<void>;
|
|
242
|
+
/**
|
|
243
|
+
* Returns the Knex dialect identifier for this database.
|
|
244
|
+
*
|
|
245
|
+
* Used for Knex configuration and feature detection.
|
|
246
|
+
*
|
|
247
|
+
* **Valid Dialect Values:**
|
|
248
|
+
* - 'sqlite3' - SQLite
|
|
249
|
+
* - 'pg' - PostgreSQL
|
|
250
|
+
* - 'mysql' - MySQL
|
|
251
|
+
* - 'mysql2' - MySQL with mysql2 driver
|
|
252
|
+
* - 'mssql' - Microsoft SQL Server
|
|
253
|
+
* - 'oracledb' - Oracle Database
|
|
254
|
+
*
|
|
255
|
+
* @abstract
|
|
256
|
+
* @returns {string} Knex dialect identifier
|
|
257
|
+
*
|
|
258
|
+
* @example
|
|
259
|
+
* // SQLite adapter
|
|
260
|
+
* getDialect(): string {
|
|
261
|
+
* return 'sqlite3';
|
|
262
|
+
* }
|
|
263
|
+
*
|
|
264
|
+
* @example
|
|
265
|
+
* // PostgreSQL adapter
|
|
266
|
+
* getDialect(): string {
|
|
267
|
+
* return 'pg';
|
|
268
|
+
* }
|
|
269
|
+
*/
|
|
270
|
+
abstract getDialect(): string;
|
|
271
|
+
/**
|
|
272
|
+
* Whether this database supports RETURNING clause in INSERT/UPDATE/DELETE.
|
|
273
|
+
* @abstract
|
|
274
|
+
*/
|
|
275
|
+
abstract readonly supportsReturning: boolean;
|
|
276
|
+
/**
|
|
277
|
+
* Whether this database has native JSON support.
|
|
278
|
+
* @abstract
|
|
279
|
+
*/
|
|
280
|
+
abstract readonly supportsJSON: boolean;
|
|
281
|
+
/**
|
|
282
|
+
* Whether this database supports UPSERT operations (INSERT ... ON CONFLICT).
|
|
283
|
+
* @abstract
|
|
284
|
+
*/
|
|
285
|
+
abstract readonly supportsUpsert: boolean;
|
|
286
|
+
/**
|
|
287
|
+
* Whether this database supports Common Table Expressions (WITH clause).
|
|
288
|
+
* @abstract
|
|
289
|
+
*/
|
|
290
|
+
abstract readonly supportsCTE: boolean;
|
|
291
|
+
/**
|
|
292
|
+
* Whether this database supports window functions.
|
|
293
|
+
* @abstract
|
|
294
|
+
*/
|
|
295
|
+
abstract readonly supportsWindowFunctions: boolean;
|
|
296
|
+
/**
|
|
297
|
+
* Whether this database supports savepoints within transactions.
|
|
298
|
+
* @abstract
|
|
299
|
+
*/
|
|
300
|
+
abstract readonly supportsSavepoints: boolean;
|
|
301
|
+
/**
|
|
302
|
+
* Database name identifier.
|
|
303
|
+
* @abstract
|
|
304
|
+
*/
|
|
305
|
+
abstract readonly databaseName: 'sqlite' | 'postgresql' | 'mysql';
|
|
306
|
+
/**
|
|
307
|
+
* Establishes database connection with authentication.
|
|
308
|
+
*
|
|
309
|
+
* This method orchestrates the complete connection flow:
|
|
310
|
+
* 1. Create authentication provider (if required)
|
|
311
|
+
* 2. Validate authentication configuration
|
|
312
|
+
* 3. Authenticate and obtain connection parameters
|
|
313
|
+
* 4. Create Knex instance with authenticated params
|
|
314
|
+
* 5. Call initialize() for adapter-specific setup
|
|
315
|
+
*
|
|
316
|
+
* **Authentication Flow:**
|
|
317
|
+
* - Direct: Use credentials as-is
|
|
318
|
+
* - SSH: Establish tunnel, connect to localhost
|
|
319
|
+
* - AWS/GCP IAM: Generate token, connect with SSL
|
|
320
|
+
*
|
|
321
|
+
* **Important Notes:**
|
|
322
|
+
* - This method is idempotent: calling twice reuses existing connection
|
|
323
|
+
* - Auth provider resources remain allocated until cleanup() is called
|
|
324
|
+
* - Knex instance is accessible via getKnex() after successful connection
|
|
325
|
+
* - Subclasses can override for special handling (e.g., SQLite)
|
|
326
|
+
*
|
|
327
|
+
* @returns {Promise<Knex>} Knex instance for database operations
|
|
328
|
+
*
|
|
329
|
+
* @throws {Error} 'Database already connected' - if connection exists
|
|
330
|
+
* @throws {Error} Auth provider validation errors
|
|
331
|
+
* @throws {Error} Authentication failures (invalid credentials, network issues)
|
|
332
|
+
* @throws {Error} Knex connection failures (database unreachable, invalid database name)
|
|
333
|
+
* @throws {Error} Initialization failures (adapter-specific setup errors)
|
|
334
|
+
*
|
|
335
|
+
* @example
|
|
336
|
+
* // Standard usage
|
|
337
|
+
* const adapter = new PostgreSQLAdapter(config);
|
|
338
|
+
* try {
|
|
339
|
+
* const knex = await adapter.connect();
|
|
340
|
+
* console.log('Connected successfully');
|
|
341
|
+
* } catch (error) {
|
|
342
|
+
* console.error('Connection failed:', error.message);
|
|
343
|
+
* await adapter.cleanup();
|
|
344
|
+
* throw error;
|
|
345
|
+
* }
|
|
346
|
+
*
|
|
347
|
+
* @example
|
|
348
|
+
* // Idempotent connection
|
|
349
|
+
* const adapter = new PostgreSQLAdapter(config);
|
|
350
|
+
* const knex1 = await adapter.connect(); // Establishes connection
|
|
351
|
+
* const knex2 = await adapter.connect(); // Returns same instance
|
|
352
|
+
* console.log(knex1 === knex2); // true
|
|
353
|
+
*/
|
|
354
|
+
connect(): Promise<Knex>;
|
|
355
|
+
/**
|
|
356
|
+
* Closes the database connection.
|
|
357
|
+
*
|
|
358
|
+
* This method closes the Knex connection pool, releasing all database connections.
|
|
359
|
+
* It does NOT release authentication provider resources (SSH tunnels, tokens) -
|
|
360
|
+
* call cleanup() to release those.
|
|
361
|
+
*
|
|
362
|
+
* **Resource Lifecycle:**
|
|
363
|
+
* - disconnect() → Closes Knex connection pool
|
|
364
|
+
* - cleanup() → Releases auth provider resources (tunnels, tokens)
|
|
365
|
+
* - Both must be called for complete cleanup
|
|
366
|
+
*
|
|
367
|
+
* **Important Notes:**
|
|
368
|
+
* - This method is idempotent: safe to call multiple times
|
|
369
|
+
* - Pending queries are allowed to complete before closing
|
|
370
|
+
* - After disconnect(), getKnex() will throw an error
|
|
371
|
+
* - Auth provider resources remain allocated until cleanup()
|
|
372
|
+
*
|
|
373
|
+
* @returns {Promise<void>}
|
|
374
|
+
*
|
|
375
|
+
* @example
|
|
376
|
+
* // Complete cleanup flow
|
|
377
|
+
* const adapter = new PostgreSQLAdapter(config);
|
|
378
|
+
* try {
|
|
379
|
+
* await adapter.connect();
|
|
380
|
+
* // ... use database ...
|
|
381
|
+
* } finally {
|
|
382
|
+
* await adapter.disconnect(); // Close DB connection
|
|
383
|
+
* await adapter.cleanup(); // Release auth resources
|
|
384
|
+
* }
|
|
385
|
+
*
|
|
386
|
+
* @example
|
|
387
|
+
* // Idempotent disconnect
|
|
388
|
+
* await adapter.disconnect(); // Closes connection
|
|
389
|
+
* await adapter.disconnect(); // Safe - no-op
|
|
390
|
+
*/
|
|
391
|
+
disconnect(): Promise<void>;
|
|
392
|
+
/**
|
|
393
|
+
* Releases authentication provider resources.
|
|
394
|
+
*
|
|
395
|
+
* This method releases resources allocated during authentication:
|
|
396
|
+
* - SSH tunnels: Closes SSH connection and releases local port
|
|
397
|
+
* - Cloud IAM: Invalidates cached tokens
|
|
398
|
+
* - Direct connections: No-op (no resources to release)
|
|
399
|
+
*
|
|
400
|
+
* **Important Notes:**
|
|
401
|
+
* - This method MUST be called after disconnect() to prevent resource leaks
|
|
402
|
+
* - Errors during cleanup are caught and logged, not thrown
|
|
403
|
+
* - This method is idempotent: safe to call multiple times
|
|
404
|
+
* - Auth provider is set to null after cleanup
|
|
405
|
+
*
|
|
406
|
+
* **Resource Leak Prevention:**
|
|
407
|
+
* Always call cleanup() in a finally block to ensure resources are released
|
|
408
|
+
* even if database operations fail.
|
|
409
|
+
*
|
|
410
|
+
* @returns {Promise<void>}
|
|
411
|
+
*
|
|
412
|
+
* @example
|
|
413
|
+
* // Proper cleanup flow
|
|
414
|
+
* const adapter = new PostgreSQLAdapter(config);
|
|
415
|
+
* try {
|
|
416
|
+
* await adapter.connect();
|
|
417
|
+
* // ... database operations ...
|
|
418
|
+
* } finally {
|
|
419
|
+
* await adapter.disconnect();
|
|
420
|
+
* await adapter.cleanup();
|
|
421
|
+
* }
|
|
422
|
+
*
|
|
423
|
+
* @example
|
|
424
|
+
* // Error handling during cleanup
|
|
425
|
+
* try {
|
|
426
|
+
* await adapter.cleanup();
|
|
427
|
+
* } catch (error) {
|
|
428
|
+
* // Cleanup errors are logged but not thrown to prevent cascading failures
|
|
429
|
+
* console.error('Cleanup failed:', error);
|
|
430
|
+
* }
|
|
431
|
+
*/
|
|
432
|
+
cleanup(): Promise<void>;
|
|
433
|
+
/**
|
|
434
|
+
* Returns the Knex.js instance for database operations.
|
|
435
|
+
*
|
|
436
|
+
* This method provides access to the underlying Knex instance for executing
|
|
437
|
+
* queries, building query chains, and accessing raw connections.
|
|
438
|
+
*
|
|
439
|
+
* **Important Notes:**
|
|
440
|
+
* - Must call connect() before calling this method
|
|
441
|
+
* - Throws error if connection not established
|
|
442
|
+
* - Returns same instance across multiple calls
|
|
443
|
+
*
|
|
444
|
+
* @returns {Knex} Knex instance for database operations
|
|
445
|
+
*
|
|
446
|
+
* @throws {Error} 'Database not connected. Call connect() first.' - if not connected
|
|
447
|
+
*
|
|
448
|
+
* @example
|
|
449
|
+
* // Standard usage
|
|
450
|
+
* const adapter = new PostgreSQLAdapter(config);
|
|
451
|
+
* await adapter.connect();
|
|
452
|
+
* const knex = adapter.getKnex();
|
|
453
|
+
* const users = await knex('users').select('*');
|
|
454
|
+
*
|
|
455
|
+
* @example
|
|
456
|
+
* // Query builder
|
|
457
|
+
* const knex = adapter.getKnex();
|
|
458
|
+
* const query = knex('orders')
|
|
459
|
+
* .where('status', 'pending')
|
|
460
|
+
* .andWhere('created_at', '>', '2024-01-01')
|
|
461
|
+
* .orderBy('created_at', 'desc');
|
|
462
|
+
*
|
|
463
|
+
* @example
|
|
464
|
+
* // Raw queries
|
|
465
|
+
* const knex = adapter.getKnex();
|
|
466
|
+
* const result = await knex.raw('SELECT * FROM users WHERE id = ?', [userId]);
|
|
467
|
+
*/
|
|
468
|
+
getKnex(): Knex;
|
|
469
|
+
/**
|
|
470
|
+
* Executes a callback within a database transaction.
|
|
471
|
+
*
|
|
472
|
+
* This method delegates to Knex's transaction management, providing:
|
|
473
|
+
* - Automatic commit on success
|
|
474
|
+
* - Automatic rollback on error
|
|
475
|
+
* - Optional isolation level configuration
|
|
476
|
+
*
|
|
477
|
+
* **Transaction Isolation Levels:**
|
|
478
|
+
* - 'serializable': Strongest isolation, prevents all anomalies
|
|
479
|
+
* - 'repeatable read': Prevents non-repeatable reads and phantom reads
|
|
480
|
+
* - 'read committed': Prevents dirty reads (default for most databases)
|
|
481
|
+
*
|
|
482
|
+
* **Important Notes:**
|
|
483
|
+
* - All database operations within callback must use the trx parameter
|
|
484
|
+
* - Do not mix transaction queries with non-transaction queries
|
|
485
|
+
* - Nested transactions use savepoints (if supported by database)
|
|
486
|
+
*
|
|
487
|
+
* @param {Function} callback - Async function receiving transaction object
|
|
488
|
+
* @param {Object} [options] - Transaction options
|
|
489
|
+
* @param {string} [options.isolationLevel] - Transaction isolation level
|
|
490
|
+
* @returns {Promise<T>} Result from callback function
|
|
491
|
+
*
|
|
492
|
+
* @throws {Error} If callback throws (transaction is rolled back)
|
|
493
|
+
*
|
|
494
|
+
* @example
|
|
495
|
+
* // Bank transfer transaction
|
|
496
|
+
* await adapter.transaction(async (trx) => {
|
|
497
|
+
* await trx('accounts')
|
|
498
|
+
* .where({ id: fromAccount })
|
|
499
|
+
* .decrement('balance', amount);
|
|
500
|
+
*
|
|
501
|
+
* await trx('accounts')
|
|
502
|
+
* .where({ id: toAccount })
|
|
503
|
+
* .increment('balance', amount);
|
|
504
|
+
*
|
|
505
|
+
* await trx('transfers').insert({
|
|
506
|
+
* from_account: fromAccount,
|
|
507
|
+
* to_account: toAccount,
|
|
508
|
+
* amount
|
|
509
|
+
* });
|
|
510
|
+
* });
|
|
511
|
+
*
|
|
512
|
+
* @example
|
|
513
|
+
* // Transaction with isolation level
|
|
514
|
+
* await adapter.transaction(async (trx) => {
|
|
515
|
+
* const balance = await trx('accounts')
|
|
516
|
+
* .where({ id: accountId })
|
|
517
|
+
* .first('balance');
|
|
518
|
+
*
|
|
519
|
+
* if (balance.balance >= amount) {
|
|
520
|
+
* await trx('accounts')
|
|
521
|
+
* .where({ id: accountId })
|
|
522
|
+
* .decrement('balance', amount);
|
|
523
|
+
* }
|
|
524
|
+
* }, { isolationLevel: 'serializable' });
|
|
525
|
+
*
|
|
526
|
+
* @example
|
|
527
|
+
* // Error handling (automatic rollback)
|
|
528
|
+
* try {
|
|
529
|
+
* await adapter.transaction(async (trx) => {
|
|
530
|
+
* await trx('users').insert({ name: 'Alice' });
|
|
531
|
+
* throw new Error('Something went wrong');
|
|
532
|
+
* await trx('logs').insert({ message: 'Never executed' });
|
|
533
|
+
* });
|
|
534
|
+
* } catch (error) {
|
|
535
|
+
* console.log('Transaction rolled back:', error.message);
|
|
536
|
+
* }
|
|
537
|
+
*/
|
|
538
|
+
transaction<T>(callback: (trx: Knex.Transaction) => Promise<T>, options?: {
|
|
539
|
+
isolationLevel?: 'serializable' | 'read committed' | 'repeatable read';
|
|
540
|
+
}): Promise<T>;
|
|
541
|
+
/**
|
|
542
|
+
* Builds Knex configuration from connection parameters.
|
|
543
|
+
*
|
|
544
|
+
* This method converts ConnectionParams (returned by auth provider) into
|
|
545
|
+
* Knex.Config format. Subclasses can override to customize configuration.
|
|
546
|
+
*
|
|
547
|
+
* **Default Behavior:**
|
|
548
|
+
* - Uses dialect from getDialect()
|
|
549
|
+
* - Passes connection params to Knex
|
|
550
|
+
* - Configures SSL if present
|
|
551
|
+
* - Merges additional params
|
|
552
|
+
*
|
|
553
|
+
* @protected
|
|
554
|
+
* @param {ConnectionParams | null} connParams - Connection parameters from auth provider
|
|
555
|
+
* @returns {Knex.Config} Knex configuration object
|
|
556
|
+
*
|
|
557
|
+
* @example
|
|
558
|
+
* // Custom configuration in subclass
|
|
559
|
+
* protected buildKnexConfig(connParams: ConnectionParams | null): Knex.Config {
|
|
560
|
+
* const baseConfig = super.buildKnexConfig(connParams);
|
|
561
|
+
* return {
|
|
562
|
+
* ...baseConfig,
|
|
563
|
+
* pool: {
|
|
564
|
+
* min: 2,
|
|
565
|
+
* max: 10,
|
|
566
|
+
* afterCreate: (conn, done) => {
|
|
567
|
+
* // Custom connection setup
|
|
568
|
+
* done(null, conn);
|
|
569
|
+
* }
|
|
570
|
+
* }
|
|
571
|
+
* };
|
|
572
|
+
* }
|
|
573
|
+
*/
|
|
574
|
+
protected buildKnexConfig(connParams: ConnectionParams | null): Knex.Config;
|
|
575
|
+
/**
|
|
576
|
+
* Inserts a row and returns the inserted record.
|
|
577
|
+
* Adapts to databases that don't support RETURNING clause.
|
|
578
|
+
* @abstract
|
|
579
|
+
*/
|
|
580
|
+
abstract insertReturning<T extends Record<string, any>>(table: string, data: Partial<T>): Promise<T>;
|
|
581
|
+
/**
|
|
582
|
+
* Upserts a row (INSERT ... ON CONFLICT UPDATE).
|
|
583
|
+
* Adapts to different upsert syntaxes across databases.
|
|
584
|
+
* @abstract
|
|
585
|
+
*/
|
|
586
|
+
abstract upsert<T extends Record<string, any>>(table: string, data: Partial<T>, conflictColumns: string[], updateColumns?: string[]): Promise<number>;
|
|
587
|
+
/**
|
|
588
|
+
* Extracts a value from a JSON column.
|
|
589
|
+
* @abstract
|
|
590
|
+
*/
|
|
591
|
+
abstract jsonExtract(column: string, path: string): Knex.Raw;
|
|
592
|
+
/**
|
|
593
|
+
* Builds a JSON object from field values.
|
|
594
|
+
* @abstract
|
|
595
|
+
*/
|
|
596
|
+
abstract jsonBuildObject(fields: Record<string, any>): Knex.Raw;
|
|
597
|
+
/**
|
|
598
|
+
* Returns current timestamp expression.
|
|
599
|
+
* @abstract
|
|
600
|
+
*/
|
|
601
|
+
abstract currentTimestamp(): Knex.Raw;
|
|
602
|
+
/**
|
|
603
|
+
* Converts Unix epoch to datetime.
|
|
604
|
+
* @abstract
|
|
605
|
+
*/
|
|
606
|
+
abstract fromUnixEpoch(epochColumn: string): Knex.Raw;
|
|
607
|
+
/**
|
|
608
|
+
* Converts datetime to Unix epoch.
|
|
609
|
+
* @abstract
|
|
610
|
+
*/
|
|
611
|
+
abstract toUnixEpoch(timestampColumn: string): Knex.Raw;
|
|
612
|
+
/**
|
|
613
|
+
* Concatenates string values.
|
|
614
|
+
* @abstract
|
|
615
|
+
*/
|
|
616
|
+
abstract concat(...values: Array<string | Knex.Raw>): Knex.Raw;
|
|
617
|
+
/**
|
|
618
|
+
* Aggregates strings with separator.
|
|
619
|
+
* @abstract
|
|
620
|
+
*/
|
|
621
|
+
abstract stringAgg(column: string, separator?: string): Knex.Raw;
|
|
622
|
+
/**
|
|
623
|
+
* Creates a savepoint within a transaction.
|
|
624
|
+
* @abstract
|
|
625
|
+
*/
|
|
626
|
+
abstract savepoint<T>(trx: Knex.Transaction, callback: (sp: Knex.Transaction) => Promise<T>): Promise<T>;
|
|
627
|
+
/**
|
|
628
|
+
* Checks if a table exists in the database.
|
|
629
|
+
* @abstract
|
|
630
|
+
*/
|
|
631
|
+
abstract tableExists(tableName: string): Promise<boolean>;
|
|
632
|
+
/**
|
|
633
|
+
* Adds an auto-increment column to a table builder.
|
|
634
|
+
* @abstract
|
|
635
|
+
*/
|
|
636
|
+
abstract autoIncrementColumn(table: Knex.CreateTableBuilder, columnName?: string): void;
|
|
637
|
+
}
|
|
638
|
+
//# sourceMappingURL=base-adapter.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"base-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/base-adapter.ts"],"names":[],"mappings":"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"}
|