Connection Management & Pooling

Connection Management and Pooling in flext-db-oracle serves as the infrastructure layer responsible for handling life-cycle operations of Oracle database connections. It utilizes the oracledb driver to provide enterprise-grade resource management, ensuring that connections are efficiently reused and safely disposed of within a Clean Architecture framework.

This module is primarily located in the infrastructure layer, abstracting the complexities of connection strings, SSL/TLS certificates, and session pooling from the higher-level application services like the FlextDbOracleApi. Sources: src/README.md:14-14, src/README.md:43-43

Architecture and Components

The connection management system follows a layered approach where the infrastructure component connection.py interacts directly with the database driver, while the application layer manages these resources through facades.

The diagram above shows the flow from high-level API calls through the service facade to the underlying connection manager. Sources: src/README.md:37-53

Key Classes and Responsibilities

Connection Lifecycle

The connection lifecycle involves initialization using validated settings, establishment of the session, and eventual termination to prevent resource leaks.

The sequence diagram illustrates the standard flow of establishing and terminating a connection. Sources: tests/unit/test_services.py:46-52, tests/unit/test_api.py:108-111

Connection Pooling

For enterprise scenarios, the system supports connection pooling to manage multiple concurrent connections efficiently. The integration tests validate behavior under load, ensuring the pool sizes correctly and acquires connections within performance thresholds. Sources: tests/integration/README.md:27-31, tests/integration/README.md:154-162

Configuration and Validation

Connection settings are managed via FlextDbOracleSettings, which enforces strict validation using Pydantic. Key parameters include:

• Host and Port: The network location of the Oracle listener.
• Service Name: The specific database instance.
• Credentials: Username and Password (often handled via FlextDbOraclePassword).
• SSL/TLS: Optional server certificate DN for secure connections.
  Sources: tests/unit/test_services.py:31-38, tests/unit/test_api.py:44-51

Error Handling and Resilience

The system uses Railway-Oriented Programming (ROP) via the r[T] pattern for all connection operations. Instead of raising raw exceptions, methods return a Result object that encapsulates success or failure metadata.

• Failure detection: The connected() method provides a boolean check for active sessions. Sources: tests/unit/test_services.py:51-51
• Graceful Recovery: The CLI and API components include logic to fail fast with descriptive errors (e.g., "No active Oracle connection") when operations are attempted on disconnected instances. Sources: tests/unit/test_cli.py:80-86
• Timeouts: Configuration includes timeout parameters to prevent application hangs during network failures. Sources: tests/unit/test_api.py:50-50

Integration with Observability

Connection operations are monitored via the observability layer. Metrics such as connection acquisition time and session health are tracked.

Summary

Connection management in flext-db-oracle provides a robust, typed interface for Oracle database interactions. By centralizing pooling logic in the infrastructure layer and enforcing strict configuration validation, the library ensures that enterprise applications maintain stable and performant database sessions. Sources: src/README.md:118-121, tests/integration/README.md:18-24