Interfaces & Protocols
Relevant source files
The following files were used as context for generating this wiki page:
The FLEXT DB Oracle library utilizes a rigorous set of Python protocols and interfaces to implement a Clean Architecture that separates domain logic from infrastructure concerns. These interfaces define the contract for database connectivity, query execution, schema introspection, and performance monitoring, ensuring that the library remains extensible and testable within the broader FLEXT ecosystem. Sources: src/flext_db_oracle/protocols.py:1-12, src/README.md:46-55
By adhering to the Dependency Inversion Principle (DIP), the library depends on these abstractions rather than concrete implementations. This allows for seamless integration of features like the plugin system and observability metrics without modifying the core API surface. Sources: src/README.md:58-62, AGENTS.md:94-98
Architectural Overview
The project is structured into layers where protocols act as the primary interface between the Foundation Layer and the Application Layer. The FlextDbOracleProtocols class extends the base flext_cli.p protocols to include Oracle-specific database operations. Sources: src/README.md:36-44, src/flext_db_oracle/protocols.py:15-32
The following diagram illustrates the relationship between the major protocol categories:
The protocol hierarchy ensures that all Oracle-specific operations inherit foundation traits like standardized Result (r[T]) types. Sources: src/flext_db_oracle/protocols.py:20-30
Core Database Protocols
Connection and Execution
The Connection protocol defines the lifecycle of an Oracle session, while the QueryExecutor handles the actual transmission of SQL to the database. Sources: src/flext_db_oracle/protocols.py:46-64, src/flext_db_oracle/protocols.py:100-112
| Protocol | Method | Purpose | Return Type |
|---|---|---|---|
| Connection | connect() | Establishes session | r[bool] |
| Connection | disconnect() | Closes session | r[bool] |
| QueryExecutor | execute_query() | Runs SQL SELECT | r[Sequence[m.Dict]] |
| QueryExecutor | execute_many() | Bulk execution | r[int] |
| QueryExecutor | fetch_one() | Retrieves single row | r[m.Dict | None] |
Sources: src/flext_db_oracle/protocols.py:49-140
Schema Introspection
The SchemaIntrospector protocol provides methods for exploring the database structure, including fetching schemas, tables, and column metadata. Sources: src/flext_db_oracle/protocols.py:165-220
The sequence shows the standard flow for metadata retrieval using protocol-defined contracts. Sources: src/flext_db_oracle/protocols.py:210-220, tests/unit/test_api.py:1044-1055
Infrastructure & Maintenance Protocols
SQL Building and DDL Generation
FLEXT DB Oracle separates the generation of SQL strings from their execution. The SqlBuilder and DdlGenerator protocols define methods for programmatically creating valid Oracle SQL. Sources: src/flext_db_oracle/protocols.py:228-265, src/flext_db_oracle/protocols.py:277-310
- SqlBuilder: Focuses on DML (Data Manipulation Language) such as
SELECT,INSERT,UPDATE, andDELETE. Sources: src/flext_db_oracle/protocols.py:231-255 - DdlGenerator: Focuses on DDL (Data Definition Language) such as
CREATE TABLE,DROP TABLE, and index management. Sources: src/flext_db_oracle/protocols.py:280-305
Plugin and Observability Systems
The library supports extensibility through a specialized plugin protocol and a metrics collector for performance monitoring. Sources: src/flext_db_oracle/protocols.py:318-355, src/flext_db_oracle/protocols.py:66-98
@runtime_checkable
class OraclePlugin(Protocol):
def initialize(self) -> p.Result[bool]: ...
def test_connection(self) -> p.Result[bool]: ...
def fetch_connection(self) -> p.Result[t.JsonValue]: ...
Sources: src/flext_db_oracle/protocols.py:69-98
| Protocol | Method | Description |
|---|---|---|
| MetricsCollector | record_metric() | Captures float values with tags |
| MetricsCollector | track_operation() | Records duration and success status |
| PluginRegistry | register_plugin() | Adds plugin to system |
| HealthCheck | health_check() | Validates overall service status |
Sources: src/flext_db_oracle/protocols.py:321-344, src/flext_db_oracle/protocols.py:368-400, tests/unit/test_services.py:210-235
Implementation Patterns
Concrete classes such as FlextDbOracleApi and FlextDbOracleServices implement these protocols. They utilize the FLEXT Core "r" pattern (Railway-oriented programming) for error handling, ensuring that every protocol method returns a Result object containing either the value or a structured error. Sources: src/README.md:65-72, tests/unit/test_api.py:110-120
Summary
The Interfaces & Protocols module forms the backbone of FLEXT DB Oracle's extensibility. By defining strict contracts for every layer of database interaction—from low-level connection management to high-level DDL generation—it enables a decoupled architecture that facilitates testing, plugin development, and comprehensive observability across enterprise Oracle environments. Sources: src/README.md:124-128, src/flext_db_oracle/protocols.py:15-32