Summary

There are 9 separate definitions of get_db() across the codebase. These should be consolidated to a single canonical definition in mcpgateway/db.py, with all other modules importing from there.

Current State

Problems Caused

1. Test complexity: Dependency overrides only affect one definition at a time, requiring tests to override multiple get_db functions. See workarounds in:

   • tests/e2e/test_oauth_protected_resource.py - overrides both main.get_db and db.get_db
   • tests/unit/mcpgateway/test_well_known.py - same pattern

2. Maintenance burden: Changes to database session handling must be replicated across all definitions.

3. Inconsistent behavior: Different modules may have subtly different session handling.

Proposed Solution

1. Analyze variant implementations: Each get_db() definition must be analyzed to determine if it can be replaced by the canonical implementation. Check for differences in:

   • Session configuration (autocommit, autoflush, expire_on_commit)
   • Error handling and rollback behavior
   • Connection pooling or scoping differences
   • Sync vs async requirements

2. Consolidate or rename:

   • If a variant can be replaced by the canonical definition, replace it with an import from mcpgateway.db
   • If a variant has legitimate differences that cannot be reconciled, rename it to reflect its purpose (e.g., get_async_db, get_scoped_db) to avoid confusion

3. Update tests to only need a single override where possible

Future Direction

This consolidation is a stepping stone toward using Python context managers (with statements) for database connection management. Having a single get_db source ensures all logic uses a singleton-like database connection pattern, which will make the transition to context managers cleaner and more consistent.

Acceptance Criteria

• All get_db() variants analyzed and documented
• Canonical get_db() in mcpgateway/db.py used wherever possible
• Variants with legitimate differences renamed to reflect their purpose
• Tests simplified to override single get_db where applicable
• All existing tests pass