Custom Protocol Extensions
Relevant source files
The following files were used as context for generating this wiki page:
Custom Protocol Extensions in the flext-dbt-oracle project define the structural and behavioral contracts required for the DBT (Data Build Tool) adapter to interface with Oracle databases. These extensions leverage a Method Resolution Order (MRO) chain that integrates base protocols from flext-core, flext-db-oracle (Oracle-specific database operations), and flext-meltano (Singer/ELT integration).
The primary purpose of these protocols is to provide a unified facade for the adapter's capabilities, including model generation, database connectivity, and pipeline execution. By adhering to the Strict YAGNI (You Ain't Gonna Need It) directive, the project focuses on essential composition through a facade pattern rather than maintaining redundant internal protocol definitions.
Sources: src/flext_dbt_oracle/protocols.py:1-25, rules.json:1-20
Protocol Architecture and Hierarchy
The protocol system is designed as a composite facade. Instead of defining unique, project-local protocols for every sub-domain (such as Transformation or Monitoring), the system inherits behaviors from established parent libraries.
Facade Composition
The FlextDbtOracleProtocols class serves as the central integration point. It inherits from both FlextDbOracleProtocols and FlextMeltanoProtocols. This structure ensures that the DBT adapter satisfies the requirements for both Oracle database interactions and Meltano-based orchestration.
The diagram above illustrates the inheritance hierarchy where the DBT Oracle protocols aggregate database and ELT capabilities.
Sources: src/flext_dbt_oracle/protocols.py:22-25, tests/protocols.py:16-21
Protocol Implementation via Domain Models
The protocols are supported by typed domain models that define the data structures exchanged during DBT workflows. These models facilitate the "Custom" aspects of the adapter, specifically regarding Oracle's unique SQL dialect and connection requirements.
Model Categories
Key domain models are nested within the FlextDbtOracleModels namespace:
| Model Class | Description | Key Fields / Methods |
|---|---|---|
DbtOracle.Model | Typed metadata for a DBT model. | name, materialization, sql_content, dependencies |
DbtOracle.ModelGenerator | Helper for deterministic metadata creation. | generate_staging_models() |
DbtOracle.OracleConnectionConfig | Oracle-specific connection parameters. | host, port, service_name, sid, protocol |
DbtOracle.OracleTableAdapter | Normalization for Oracle table metadata. | schema_name, table_name, relation_name |
Sources: src/flext_dbt_oracle/models.py:20-140
Connection Protocol Logic
The connection protocol requires specific handling of Oracle identifiers. The OracleConnectionConfig model implements logic to differentiate between Service Names and SIDs (System Identifiers) to generate valid DSNs.
Behavioral Protocols and Utilities
Operational behavior is defined through a typed facade in the utilities layer. The FlextDbtOracleUtilities.DbtOracle.Client acts as the primary orchestrator for discovery, extraction, and pipeline execution.
Client Operations
The client implementation encapsulates the following workflow steps:
- Discovery: Identifying candidate tables for modeling (e.g.,
customers,orders). - Extraction: Retrieving sample payloads or metadata from the Oracle instance.
- Pipeline Execution: Running the end-to-end transformation flow for selected tables.
Sources: src/flext_dbt_oracle/utilities.py:16-56
Runtime Configuration Protocol
The FlextDbtOracleSettings class implements the configuration protocol, providing a single source of truth (SSOT) for environment-driven parameters. It includes specific validation for Oracle-centric performance tunables.
Integration Rules and Constraints
The rules.json file defines the external constraints and dependencies that the protocol extensions must satisfy. This includes mandatory fields for Oracle profiles and materialization strategies.
SQL Dialect and Materialization
The adapter explicitly supports a subset of DBT materializations and Oracle-specific SQL features:
- Supported Materializations:
table,view,incremental,snapshot. - Incremental Strategies:
merge,delete+insert. - Dialect Rules: Uppercase default case sensitivity and a 128-character identifier limit.
Sources: rules.json:30-60
Summary
Custom Protocol Extensions in flext-dbt-oracle provide a strictly-typed, facade-based interface for DBT operations on Oracle. By composing base protocols from the flext ecosystem and enforcing Oracle-specific validation rules through Pydantic-based models and settings, the system ensures a consistent and predictable integration for enterprise data transformations.