Protocols & Interfaces
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Protocols and interfaces in the flext-dbt-oracle project define the structural contracts and behavioral expectations for the dbt adapter integrated with Oracle databases. They facilitate a decoupled architecture where components depend on abstractions rather than concrete implementations, adhering to the Dependency Inversion Principle (DIP). This system ensures interoperability between the core FLEXT ecosystem, the Meltano integration layer, and the specific Oracle database drivers.
The primary role of these interfaces is to provide a unified facade for dbt operations, including model generation, connection management, and pipeline execution. By composing protocols from flext-db-oracle and flext-meltano, the project establishes a robust Method Resolution Order (MRO) that leverages existing functionalities while allowing for Oracle-specific specializations in data transformation and SQL dialect handling.
Sources: src/flext_dbt_oracle/protocols.py:1-24, AGENTS.md:195-201, rules.json:1-15
Architectural Composition
The protocol layer is designed as a facade that aggregates multiple upstream interfaces. This approach allows the flext-dbt-oracle package to inherit behaviors related to both general database operations and Meltano-based orchestration.
The Protocol Facade
The central interface, FlextDbtOracleProtocols, serves as a namespace and type-checking boundary. It inherits from FlextDbOracleProtocols (providing Oracle-specific database interactions) and FlextMeltanoProtocols (providing Singer/Meltano lifecycle and discovery capabilities).
The diagram shows the inheritance hierarchy where FlextDbtOracleProtocols composes functionalities from both database-specific and orchestration-specific parent protocols.
Sources: src/flext_dbt_oracle/protocols.py:17-21
Interface Governance and YAGNI
The project follows a strict "You Ain't Gonna Need It" (YAGNI) policy. Previously, the system contained eight granular internal protocols (e.g., Modeling, Transformation, Performance). These were removed because they had no workspace consumers or runtime-checkable implementations, leaving only the primary facade to avoid dead code and maintain a clean API surface.
Sources: src/flext_dbt_oracle/protocols.py:3-13, AGENTS.md:191-193
Key Functional Interfaces
While the top-level protocols provide the type-checking contract, specific functional interfaces are implemented via utility clients and model generators to handle the actual logic of the dbt adapter.
Pipeline and Client Interface
The DbtOracle.Client within the utilities module acts as the primary execution interface for dbt pipelines on Oracle. It defines the contract for table discovery and data extraction.
| Feature | Description | File Reference |
|---|---|---|
discover_tables | Returns candidates for the modeling flow (e.g., customers, orders). | utilities.py:27 |
extract_table_data | Fetches sample payloads for deterministic modeling. | utilities.py:31 |
run_pipeline | Coordinates the full discovery and extraction flow for dbt models. | utilities.py:39 |
test_connection | Validates connectivity to the Oracle instance. | utilities.py:53 |
Sources: src/flext_dbt_oracle/utilities.py:21-59
Model Generation Interface
The ModelGenerator provides a deterministic interface for creating dbt staging models based on source metadata. It ensures that the generated SQL follows standard dbt patterns (e.g., using the source() macro).
This diagram illustrates the flow of generating staging model definitions from a list of source table names.
Sources: src/flext_dbt_oracle/models.py:53-73
Integration Standards
The interfaces are governed by a set of rules defined in the rules.json file, which specifies versioning and compatibility constraints for the adapter.
Adapter Constraints
The dbt adapter must adhere to specific API and versioning standards to function within the FLEXT ecosystem:
- dbt Core Version:
>=1.8.0 - Adapter API Version:
v12 - Modern dbt Only: Strict enforcement of modern dbt patterns, excluding legacy PostgreSQL dependencies.
- Connection Management: Delegated to
flext_db_oracleprimitives.
Sources: rules.json:9-15, rules.json:104-108
Mapping and Dialect Protocols
The system defines how dbt types map to Oracle-specific SQL types through a configuration interface.
| dbt Type | Oracle SQL Target |
|---|---|
string | VARCHAR2(4000) |
text | CLOB |
boolean | NUMBER(1,0) |
float | BINARY_DOUBLE |
timestamp | TIMESTAMP |
Sources: rules.json:42-60
Testing Protocols
Testing interfaces combine the production protocols with testing-specific capabilities. The TestsFlextDbtOracleProtocols class inherits from FlextTestsProtocols and FlextDbtOracleProtocols, providing a unified surface for asserting behavior and verifying configurations.
class TestsFlextDbtOracleProtocols(
FlextTestsProtocols,
FlextDbtOracleProtocols,
):
"""Test protocols combining FlextTestsProtocols and FlextDbtOracleProtocols."""
Sources: tests/protocols.py:17-22
Conclusion
The "Protocols & Interfaces" system in flext-dbt-oracle establishes a clean, type-safe boundary between the dbt orchestration logic and the underlying Oracle database. By using a facade pattern and strict MRO inheritance, it ensures that the project remains extensible and compliant with the broader FLEXT ecosystem standards. This architecture minimizes redundancy and enforces a single source of truth for both data models and execution logic.
Sources: src/flext_dbt_oracle/protocols.py:1-24, AGENTS.md:186-189