Settings & Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_dbt_oracle/settings.py
• src/flext_dbt_oracle/models.py
• src/flext_dbt_oracle/base.py
• rules.json
• tests/unit/_config_parts/validation.py
• tests/unit/_config_parts/connection.py

Introduction

Settings & Configuration in flext-dbt-oracle provides a centralized, typed system for managing environment-driven parameters required for dbt operations on Oracle databases. It leverages Pydantic-based models to ensure validation and consistency across database connections, performance tuning, and dbt materialization strategies.

The system is designed to load configuration from environment variables (prefixed with FLEXT_DBT_ORACLE_) and supports complex validation logic, such as verifying connection pool boundaries and generating dynamic connection strings for Oracle SID or Service Name configurations.

Sources: src/flext_dbt_oracle/settings.py:16-25, rules.json:115-125

Core Configuration Model

The primary configuration interface is the FlextDbtOracleSettings class. This class inherits from FlextSettingsBase and serves as the single source of truth for runtime components.

The diagram shows the inheritance and primary attributes of the settings class used to manage Oracle-dbt integrations.
Sources: src/flext_dbt_oracle/settings.py:16-52, src/flext_dbt_oracle/base.py:14-20

Connection Parameters

The module supports various connection methods to Oracle, including Service Name and SID-based identifiers. It also handles protocol selection between standard TCP and secure TCPS.

Parameter	Type	Default	Description
oracle_host	str	Default Constant	Database host address
oracle_port	int	1521	Database listener port
oracle_username	str	"oracle"	Database user
oracle_password	SecretStr	""	Database password (masked in logs)
oracle_service_name	str	Default Constant	Oracle Service Name
sid	str | None	None	Optional Oracle System ID
protocol	Literal["tcp", "tcps"]	"tcp"	Connection protocol

Sources: src/flext_dbt_oracle/settings.py:27-52, rules.json:120-125

Performance & Resource Tuning

Performance settings control how the adapter interacts with the Oracle database, specifically managing connection lifecycle and query execution batches.

Connection Pooling

The system enforces strict validation on connection pool sizes to prevent runtime exhaustion or misconfiguration. A model_validator ensures that pool_max_size is always greater than or equal to pool_min_size.

@u.model_validator(mode="after")
def validate_pool_sizes(self) -> FlextDbtOracleSettings:
    """Validate pool upper bound against minimum."""
    if self.pool_max_size < self.pool_min_size:
        msg = "Pool max size must be >= pool min size"
        raise ValueError(msg)
    return self

Sources: src/flext_dbt_oracle/settings.py:126-132, tests/unit/_config_parts/validation.py:65-75

Tuning Options

Option	Type	Default	Description
pool_min_size	int	1	Minimum concurrent connections
pool_max_size	int	10	Maximum concurrent connections
query_timeout	int	300	Seconds before query cancellation
fetch_size	int	1000	Records fetched per batch
retry_attempts	int	3	Max connection retries

Sources: src/flext_dbt_oracle/settings.py:102-124, rules.json:107-113

Dbt Integration Flow

The configuration is converted into dbt-compatible profiles and internal Oracle connection configurations through specialized transformation methods.

The flow shows how raw environment configuration is parsed into the settings object and then distributed to either the dbt engine or the low-level database client.
Sources: src/flext_dbt_oracle/base.py:28-41, src/flext_dbt_oracle/settings.py:146-168

Dbt Profile Mapping

The FlextDbtOracleServiceBase class maps internal settings to the standard dbt profile structure:

• type: Fixed to oracle.
• user: Maps from oracle_username.
• schema: Uses schema_name or a default fallback.
• project: Uses the canonical dbt-oracle name.

Sources: src/flext_dbt_oracle/base.py:32-41, rules.json:115-125

Computed Configuration Properties

The settings model provides computed fields that resolve complex logic for downstream consumers.

• database_identifier: Returns sid if provided; otherwise, returns oracle_service_name.
• effective_schema: Returns the explicit schema_name if set; otherwise, defaults to the oracle_username.
• connection_string: Generates a masked SQLAlchemy-style DSN. It uses a : separator for SIDs and a / separator for Service Names.

Sources: src/flext_dbt_oracle/settings.py:139-155, tests/unit/_config_parts/connection.py:12-35

Validation Logic

Configuration integrity is maintained through multi-layer validation:

1. Type Constraint: Ensures ports are valid integers and protocols match allowed literals (tcp/tcps).
2. Schema Constraint: Ensures required fields like host and username are present during construction.
3. Logical Constraint: Validates that numeric ranges (like pool sizes) are coherent.

Sources: tests/unit/_config_parts/validation.py:14-63, rules.json:23-28

Summary

The Settings & Configuration module in flext-dbt-oracle acts as a robust bridge between environment-based deployment configurations and the specific requirements of the Oracle database and dbt framework. By utilizing typed Pydantic models, the system ensures that performance parameters and connection details are validated before any database operation is attempted, reducing runtime failures.