Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
flext-dbt-oracle is a specialized integration module designed to bridge dbt workflows with Oracle Database environments. It functions as a modern dbt adapter extension, leveraging the flext-core and flext-db-oracle frameworks to provide typed metadata, connection management, and automated model generation for enterprise data transformation pipelines.
The project is structured to enforce strict governance, utilizing lazy loading for performance and inheriting from a multi-tier MRO (Method Resolution Order) chain that includes flext-meltano and flext-db-oracle. This ensures that Oracle-specific SQL dialects and materialization strategies (like incremental and snapshot) are handled natively while maintaining compatibility with dbt Core v1.8.0+.
Sources: README.md:9-11, rules.json:7-20, src/flext_dbt_oracle/models.py:14-18
Core System Hierarchy
The architecture follows a layered inheritance pattern. The primary facade classes in this module aggregate functionality from lower-level database adapters and higher-level orchestration frameworks.
The diagram above illustrates how FlextDbtOracleModels and FlextDbtOracleServiceBase compose functionality from Meltano-specific dbt services and Oracle-specific database models.
Sources: src/flext_dbt_oracle/models.py:14-20, src/flext_dbt_oracle/base.py:14-18
Component Breakdown
1. Data Models and Metadata
The module defines a strict schema for dbt model metadata through the FlextDbtOracleModels.DbtOracle.Model class. This includes support for Oracle-specific materialization strategies and deterministic staging model generation.
| Field | Type | Description |
|---|---|---|
name | str | Canonical dbt model name. |
table_name | str | Physical table name in Oracle. |
materialization | Enum | Strategy: table, view, incremental, or snapshot. |
sql_content | str | The SQL body of the model. |
dependencies | Sequence[str] | Upstream dbt model dependencies. |
Sources: src/flext_dbt_oracle/models.py:24-60, rules.json:48-54
2. Connection Management
Connections are managed through OracleConnectionConfig, which supports both service_name and sid identifiers. It handles secure password storage using SecretStr and provides computed DSN (Data Source Name) strings.
This flow shows the logic used to construct Oracle connection strings based on the provided identifier type.
Sources: src/flext_dbt_oracle/models.py:80-136, src/flext_dbt_oracle/base.py:29-42
3. Service Layer
The FlextDbtOracleServiceBase acts as the primary runtime coordinator. It fetches global settings and translates them into a dbt-compatible connection_profile.
- dbt Project Name: Defaulted to
dbt-oracle. - Profile Type: Explicitly set to
oracle. - Validation: Uses Pydantic-based settings validation (e.g., verifying pool sizes where
pool_min_size<=pool_max_size).
Sources: src/flext_dbt_oracle/base.py:14-43, tests/unit/_config_parts/validation.py:73-83
SQL Dialect & Materializations
The module implements a specific SQL dialect configuration for Oracle, ensuring compatibility with dbt's expectations for identifier quoting and case sensitivity.
| Feature | Configuration | Source |
|---|---|---|
| Dialect | oracle | rules.json:40 |
| Case Sensitivity | uppercase_default | rules.json:45 |
| Identifier Length | Max 128 characters | rules.json:46 |
| Strategies | merge, delete+insert | rules.json:52 |
Execution Flow
The following sequence diagram represents the typical discovery and pipeline execution flow handled by the FlextDbtOracleUtilities.DbtOracle.Client.
This diagram depicts how the utility client coordinates data discovery and extraction tasks within the Oracle ecosystem.
Sources: src/flext_dbt_oracle/utilities.py:22-68
Governance and Quality Gates
As a flext-core based module, it adheres to strict engineering laws defined in AGENTS.md. Key architectural constraints include:
- No Module-Level Loggers: Loggers must not be defined at the top level of package modules to maintain clean import chains.
- Top-Level Function Prohibition: All logic must be encapsulated within classes to support MRO-based extension.
- Lazy Exports: The package uses
install_lazy_exportsto minimize startup overhead by deferring imports until attributes are accessed.
Sources: src/flext_dbt_oracle/init.py:60-75, tests/unit/test_module_governance.py:65-98, AGENTS.md:12-25
Summary
The flext-dbt-oracle architecture provides a robust, typed interface for Oracle-based dbt operations. By combining Pydantic models for configuration, deterministic metadata generation, and a service layer that bridges dbt's profile requirements with Oracle's specific connectivity needs, it ensures scalable and maintainable data transformation pipelines.