Project Home
Relevant source files
The following files were used as context for generating this wiki page:
The flext-dbt-oracle project provides a modern dbt (data build tool) adapter and integration layer specifically optimized for Oracle Databases. Built upon the flext-core framework, it facilitates typed data transformations by composing functionalities from flext-db-oracle and flext-meltano. The project aims to provide a robust, enterprise-grade integration for Oracle-backed dbt workflows, ensuring strict type safety and modern SQL patterns.
Sources: README.md:1-10, rules.json:1-10, pyproject.toml:23-32
System Architecture
The architecture follows a modular approach where dbt capabilities are layered on top of core database and orchestration libraries. It utilizes a "Parent MRO (Method Resolution Order) chain" to inherit behaviors from base packages, specifically integrating Singer/Meltano patterns for data movement and Oracle-specific SQL execution.
Module Hierarchy
The following diagram illustrates how flext-dbt-oracle inherits and composes its domain namespace from other core modules.
Key Components and Data Models
The project defines structured models for handling dbt metadata and Oracle connection configurations. These models use Pydantic-based validation to ensure configuration integrity.
Dbt Oracle Models
The FlextDbtOracleModels class acts as a namespace for typed dbt metadata.
| Component | Description |
|---|---|
DbtOracle.Model | Typed payload containing dbt model metadata including name, materialization, and SQL content. |
DbtOracle.ModelGenerator | A helper for generating deterministic staging model metadata from source tables. |
DbtOracle.OracleConnectionConfig | Detailed configuration for Oracle connections including DSN and DSN generation logic. |
DbtOracle.OracleTableAdapter | Normalizes Oracle table metadata (schema and table names) into fully qualified relations. |
Sources: src/flext_dbt_oracle/models.py:25-156
Data Flow for Staging Generation
The ModelGenerator simplifies the creation of dbt staging layers by mapping source tables to dbt source functions.
Sources: src/flext_dbt_oracle/models.py:72-87
Configuration and Rules
The adapter is governed by a strict set of rules defined in rules.json, which mandates modern dbt patterns and prohibits legacy PostgreSQL dependencies.
Technical Constraints
- dbt Core Version:
>=1.8.0 - Adapter API Version:
v12 - SQL Dialect: Oracle (Uppercase default, 128 character identifier limit)
- Forbidden Dependencies:
dbt-postgres,psycopg2,postgresql
Sources: rules.json:11-20, rules.json:101-106
Connection Management
Connection profiles for Oracle-backed workflows are dynamically generated through the service base.
# From src/flext_dbt_oracle/base.py:38-48
@property
def connection_profile(self) -> t.JsonMapping:
active_settings = self.settings
return {
"type": "oracle",
"host": active_settings.oracle_host,
"port": active_settings.oracle_port,
"user": active_settings.oracle_username,
"password": active_settings.oracle_password.get_secret_value(),
"service_name": active_settings.oracle_service_name,
"schema": active_settings.schema_name or c.DbtOracle.DEFAULT_SCHEMA_NAME,
"project": self.dbt_project_name,
}
Sources: src/flext_dbt_oracle/base.py:38-48
SQL Support and Materializations
The adapter supports standard dbt materialization strategies adapted for Oracle syntax.
| Feature | Supported Strategies / Details |
|---|---|
| Materializations | table, view, incremental, snapshot |
| Incremental Strategies | merge, delete+insert |
| SQL Features | CTEs (recursive), Window functions, Analytic functions, Lateral joins, Pivot/Unpivot |
| Data Type Mapping | boolean -> NUMBER(1,0), string -> VARCHAR2(4000), text -> CLOB |
Sources: rules.json:44-53, rules.json:54-75, rules.json:76-85
Governance and Quality Gates
The project adheres to the Universal Agent Engineering Core standards. This ensures that all changes are validated by construction and that configuration remains the single source of truth (SSOT).
- Tests validate config: Tests must read expected values from the same typed SSOT as production code; they are forbidden from hardcoding scalar values.
- Quality Gates: The project uses
ruff,pyrefly,pyright,mypy, andpytestfor continuous validation. - Fix Forward: Reverting shared work is forbidden; developers must integrate and fix the current state.
Sources: AGENTS.md:15-60, AGENTS.md:215-225, README.md:38-42
flext-dbt-oracle serves as the bridge between dbt's transformation logic and Oracle's enterprise database capabilities, ensuring that data engineers can leverage modern dbt features while maintaining the performance and security standards required by Oracle environments.