Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
The flext-dbt-oracle project provides a modern dbt adapter specifically designed for Oracle Database environments. It integrates dbt models into Oracle-based data workflows by leveraging the flext-core and flext-db-oracle libraries to ensure robust connection management, typed metadata, and high-performance SQL execution. The primary purpose of this module is to enable enterprise-grade data transformation using Oracle-specific features such as sequences, analytic functions, and optimized materialization strategies.
Sources: README.md:1-12, rules.json:1-10
Prerequisites and Installation
System Requirements
The project requires Python version 3.13 (specifically 3.13.x < 3.14). It depends on several core flext libraries and standard data libraries like agate and pydantic.
Sources: pyproject.toml:34-45, pyproject.toml:70-71
Core Dependencies
| Dependency | Version / Source | Description |
|---|---|---|
dbt-common | @ flext/relax-deps | Foundation for dbt operations |
flext-core | Workspace / Latest | Core framework utilities |
flext-db-oracle | Workspace / Latest | Oracle-specific database client |
oracledb | >=3.2.0 | Official Oracle Python driver |
pydantic | >=2.13.3 | Data validation and settings management |
Sources: pyproject.toml:34-45, rules.json:96-104
Configuration and Environment
Connection Parameters
Configuration is primarily managed through FlextDbtOracleSettings, which utilizes environment variables or Pydantic models to define the connection to the Oracle instance.
The diagram shows the flow from raw environment variables to the final DSN used for database connection.
Sources: src/flext_dbt_oracle/models.py:77-105, tests/conftest.py:30-40
Required Environment Variables
To get started, the following environment variables should be defined in the development or production environment:
| Variable | Description | Default (if applicable) |
|---|---|---|
ORACLE_HOST | Database host address | localhost |
ORACLE_PORT | Listener port | 1521 |
ORACLE_USERNAME | Database user | - |
ORACLE_PASSWORD | User password | - |
ORACLE_SERVICE_NAME | Oracle Service Name | XEPDB1 |
ORACLE_SCHEMA | Target dbt schema | HR |
Sources: rules.json:111-122, tests/unit/_config_parts/construction.py:15-28
Data Models and Materializations
Supported Materializations
The adapter supports standard dbt materialization strategies adapted for Oracle's SQL dialect.
- Table: Full refresh of data.
- View: Virtual relations.
- Incremental: Efficient updates using
mergeordelete+insertstrategies. - Snapshot: Point-in-time data tracking.
Sources: rules.json:42-50
Oracle Data Type Mapping
dbt standard types are mapped to Oracle-specific types to ensure schema consistency:
string->VARCHAR2(4000)integer->NUMBER(38,0)float/double->BINARY_DOUBLEboolean->NUMBER(1,0)text->CLOB
Sources: rules.json:52-73
Basic Usage
Staging Model Generation
The project includes a ModelGenerator class to automate the creation of staging models from source tables. This ensures a consistent SQL structure across the project.
# Example of generating staging models
# src/flext_dbt_oracle/models.py:61-75
def generate_staging_models(self, source_tables: t.StrSequence) -> t.SequenceOf[FlextDbtOracleModels.DbtOracle.Model]:
return [
FlextDbtOracleModels.DbtOracle.Model(
name=f"stg_oracle_{table}",
table_name=f"stg_{table}",
sql_content=f"select * from {{{{ source('oracle', '{table}') }}}}",
description=f"Staging model for {table}",
)
for table in source_tables
]
Sources: src/flext_dbt_oracle/models.py:61-75
Command Line Interface
The package provides a CLI tool registered as flext-dbt-oracle. Standard development tasks are executed via make verbs:
make check: Runs linting and static analysis (Ruff, Mypy, Pyright).make test: Executes the pytest suite.make gen: Regenerates auto-generated lazy export maps and versions.
Sources: pyproject.toml:67, README.md:29-32, AGENTS.md:143-150
Testing Infrastructure
The project uses a Docker-based testing environment to ensure compatibility with real Oracle instances. The tests/conftest.py file manages a shared Oracle container (flext-oracle-db-test) for integration tests.
Sequence illustrating the lifecycle of the Oracle container during a test session.
Sources: tests/conftest.py:20-55
Governance and Quality Gates
All development must follow the "Universal Agent Law" defined in AGENTS.md. This includes maintaining "Continuous Green" status where all PRs must pass linting, type checks, and coverage gates before merging. Tests are prohibited from hardcoding configuration values and must read from the Single Source of Truth (SSOT).
Sources: AGENTS.md:50-59, AGENTS.md:200-210, README.md:29-32
Summary
flext-dbt-oracle provides a robust bridge between dbt and Oracle databases, emphasizing typed configuration, automated model generation, and containerized testing. By adhering to the flext ecosystem's quality gates and governance, it ensures that Oracle data transformations are maintainable, performant, and reliable.