Settings Environment Customization
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The settings environment customization within the flext-dbt-oracle project provides a strongly typed, environment-aware configuration layer for dbt adapters targeting Oracle databases. This system leverages Pydantic models to define, validate, and inject configuration values derived from environment variables, ensuring that database connections and dbt materialization strategies remain consistent across different runtime environments.
The primary mechanism for this customization is the FlextDbtOracleSettings class, which defines the schema for Oracle-specific connection parameters, performance tuning, and dbt execution metadata. By utilizing an environment prefix of FLEXT_DBT_ORACLE_, the system automatically maps external environment variables to internal configuration fields.
Sources: src/flext_dbt_oracle/settings.py:19-24, src/flext_dbt_oracle/base.py:15-18
Core Configuration Architecture
The configuration system is built upon a hierarchical inheritance structure. FlextDbtOracleSettings inherits from FlextSettingsBase, while specialized service classes like FlextDbtOracleServiceBase provide a managed interface to access these settings globally.
Settings Lifecycle and Flow
The following diagram illustrates how settings are initialized from the environment and utilized by dbt services.
The system reads environment variables, validates them using Pydantic's model_validator (e.g., ensuring connection pool bounds), and registers them globally for service consumption.
Sources: src/flext_dbt_oracle/settings.py:118-124, src/flext_dbt_oracle/base.py:30-33
Configuration Parameters
The settings are categorized into connection details, performance tuning, and dbt-specific strategy markers.
Database Connection Parameters
These fields define the physical path to the Oracle instance.
| Field | Type | Default | Description |
|---|---|---|---|
oracle_host | str | localhost | Database host address |
oracle_port | PortNumber | 1521 | Database listener port |
oracle_username | str | oracle | Database user |
oracle_password | SecretStr | "" | Database password (masked) |
oracle_service_name | str | XEPDB1 | Oracle Service Name |
sid | str | None | None | Oracle SID (optional) |
protocol | tcp | tcps | tcp | Network protocol |
Sources: src/flext_dbt_oracle/settings.py:26-53, rules.json:115-122
Performance and Pooling
The adapter includes settings to manage resource utilization and query execution limits.
| Field | Type | Default | Description |
|---|---|---|---|
pool_min_size | PositiveInt | 1 | Minimum connection pool size |
pool_max_size | PositiveInt | 10 | Maximum connection pool size |
query_timeout | PositiveInt | 300 | Timeout in seconds |
fetch_size | PositiveInt | 1000 | Rows to fetch per batch |
Sources: src/flext_dbt_oracle/settings.py:84-100, rules.json:76-83
Logic and Computed Properties
The FlextDbtOracleSettings class implements business logic through computed fields to provide derived configuration formats for various consumers.
Identifier Resolution
The system must resolve whether to use a SID or a service_name for the Oracle connection. This is handled by the database_identifier property.
@u.computed_field(return_type=str)
@property
def database_identifier(self) -> str:
"""Service name or SID identifier."""
return self.sid or self.oracle_service_name
Sources: src/flext_dbt_oracle/settings.py:133-137, src/flext_dbt_oracle/models.py:108-113
Connection String Assembly
A masked connection string is generated for logging and internal identification purposes, handling the syntax difference between SID (uses :) and Service Name (uses /).
Sources: src/flext_dbt_oracle/settings.py:145-155, tests/unit/_config_parts/connection.py:16-29
Validation and Governance
Configuration integrity is enforced through strict typing and automated unit tests.
Validation Rules
- Pool Bounds: The system ensures
pool_max_sizeis always greater than or equal topool_min_size. - Enums: Fields like
materializationandprotocolare restricted to literal sets (e.g.,table,view,incremental,snapshot). - Governance: Top-level functions and module-level loggers are prohibited in package modules to maintain architectural purity.
Conclusion
The settings environment customization in flext-dbt-oracle acts as a robust Single Source of Truth (SSOT). By combining Pydantic validation with specific Oracle requirements, the project ensures that dbt workflows are configured accurately via environment variables, supporting secure password handling and optimized connection pooling for enterprise data environments.