API Runtime Orchestrator
Relevant source files
The following files were used as context for generating this wiki page:
The API Runtime Orchestrator, primarily implemented via FlextDbOracleApiRuntime, serves as the core runtime behavior layer for the public Oracle Database API facade. It integrates Clean Architecture principles to separate the public application surface from the underlying infrastructure and domain logic. By utilizing Method Resolution Order (MRO), it composes the necessary services to provide high-level Oracle operations including connection management, query execution, and schema introspection.
This component acts as the primary gateway for the FLEXT DB Oracle library, ensuring that all database interactions are mediated through validated settings and standardized flext-core result patterns. Sources: src/README.md:16-19, src/flext_db_oracle/services/api_runtime.py:20-25
Architectural Positioning
The Orchestrator resides in the Application Layer of the project hierarchy. It relies on the Infrastructure Layer (for connection pooling and settings) and the Domain Layer (for metadata models and types) to fulfill its responsibilities.
Layered Architecture Relationship
The following diagram illustrates how the runtime orchestrator bridges the application surface to the underlying Oracle services.
Core Components and Initialization
The Orchestrator is initialized with a FlextDbOracleSettings object, which undergoes validation to ensure mandatory criteria such as host, port, username, and password are met.
Lifecycle Management
The orchestrator implements the Python context manager protocol (__enter__ / __exit__) to ensure safe resource handling. When entering a with block, it automatically attempts to establish a connection; upon exit, it triggers cleanup via the underlying services.
| Component | Responsibility |
|---|---|
_oracle_config | Stores validated Pydantic-based configuration. |
_services | Instance of FlextDbOracleServices for actual DB operations. |
_dispatcher | Handles command dispatching for decoupled service execution. |
_context_name | Identifies the API instance, defaulting to oracle-api. |
Sources: src/flext_db_oracle/services/api_runtime.py:28-60, tests/unit/test_api.py:410-425
Connection Handling and Factory Methods
The Orchestrator provides multiple entry points for instantiation to accommodate different environment setups.
from_env: Resolves settings from environment variables (e.g.,ORACLE_HOST).from_url: Parses a standard Oracle connection string into a settings object.from_config: Directly accepts a pre-constructed settings instance.
Connection Flow
This sequence diagram shows the internal flow when an application calls .connect() on the Orchestrator.
Execution and Data Transformation
The Orchestrator mediates between raw SQL execution and domain-specific models. It supports single query execution (query, query_one), bulk operations (execute_many), and direct statement execution (execute_sql).
Parameter Normalization
Before execution, query parameters are normalized into a canonical ConfigMap. This ensures that diverse input types are handled consistently by the lower-level dispatcher and services. Sources: src/flext_db_oracle/services/api_runtime.py:95-124
Data Model Conversion
Raw sequence data from Oracle is converted into high-level domain entities such as m.DbOracle.QueryResult.
Schema and Metadata Introspection
The Orchestrator provides methods to introspect the Oracle database structure. It serves as an interface for:
- Fetching available schemas (
fetch_schemas). - Listing tables within a schema (
fetch_tables). - Retrieving column-level details (
fetch_columns). - Extracting primary key constraints (
fetch_primary_keys).
These operations return domain models (e.g., Sequence[m.DbOracle.Column]) rather than raw database tuples, facilitating Type-Safe development. Sources: src/flext_db_oracle/services/api_runtime.py:192-230, tests/unit/test_services.py:530-550
Plugin and Observability Integration
To adhere to the Open/Closed principle, the Orchestrator integrates a plugin system and observability metrics.
- Plugin Registry: Allows registration of utility or monitoring plugins via
register_pluginandunregister_plugin. - Metrics: Fetches runtime performance data through
fetch_observability_metrics. - Health Check: Reports connection and service status via
fetch_health_status.
Sources: src/README.md:65-71, src/flext_db_oracle/services/api_runtime.py:202-210, tests/unit/test_api.py:750-775
Summary
The API Runtime Orchestrator acts as the functional engine of the FLEXT DB Oracle library. By composing services through a runtime mixin, it provides a robust, validated, and observable interface for enterprise-grade Oracle operations. It strictly follows Clean Architecture, ensuring that the application layer remains decoupled from the specific intricacies of the oracledb driver while providing rich domain-driven metadata and results.
Sources: src/README.md:113-116, src/flext_db_oracle/services/api_runtime.py:28-40