Environment & Settings Management
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Environment and Settings Management in the flext-dbt-oracle-wms project provides a structured, type-safe approach to configuring Oracle WMS data transformations. The system leverages Pydantic-based settings, environment variable prefixes, and DBT-specific configurations to ensure consistency across development, staging, and production environments. This infrastructure governs how the application connects to Oracle WMS APIs, manages DBT execution parameters, and defines data quality thresholds.
The architecture is built upon the flext-core foundation, utilizing a "Single Source of Truth" (SSOT) principle where configuration facts are owned by specific YAML files or typed settings classes. This ensures that tests, production code, and documentation remain synchronized with the current environment state.
Sources: AGENTS.md:21-25, src/flext_dbt_oracle_wms/settings.py:15-20
Core Settings Architecture
The project utilizes a tiered settings hierarchy. At the Python level, FlextDbtOracleWmsSettings acts as the primary runtime configuration handler. It inherits from FlextSettingsBase and uses an environment variable prefix to automatically load values from the system environment.
Settings Implementation
The FlextDbtOracleWmsSettings class defines the critical parameters required for both the Oracle WMS client and the DBT transformation engine.
class FlextDbtOracleWmsSettings(FlextSettingsBase):
"""Runtime configuration for dbt Oracle WMS."""
model_config: ClassVar[m.SettingsConfigDict] = m.SettingsConfigDict(
env_prefix="FLEXT_DBT_ORACLE_WMS_", extra="ignore"
)
# ... fields for WMS URL, DBT threads, and environment status
Sources: src/flext_dbt_oracle_wms/settings.py:17-23
Configuration Parameters
The following table outlines the primary configuration options available in the Python runtime:
| Option | Type | Default | Description |
|---|---|---|---|
oracle_wms_environment | str | "development" | Target WMS environment (e.g., development, production). |
oracle_wms_base_url | str | "" | The base URL for the Oracle WMS API endpoint. |
dbt_threads | int | 4 | Number of threads for parallel DBT execution. |
dbt_target | str | "dev" | The DBT profile target to utilize. |
required_fields_per_entity | Mapping | {} | Validation rules for specific WMS entities. |
Sources: src/flext_dbt_oracle_wms/settings.py:25-48
DBT Environment Profiles
The project manages database connections and environment-specific behaviors through profiles.yml and dbt_project.yml. These files define how data is processed in different stages of the lifecycle.
Connection Mapping
The system supports multiple adapter types depending on the environment, ranging from local development with DuckDB to production-grade PostgreSQL.
The diagram above illustrates how environment variables drive the selection of different database backends and connection parameters.
Sources: profiles.yml:8-52
Environment Variables for DBT
DBT configurations are primarily driven by the following environment variables:
| Variable | Default | Purpose |
|---|---|---|
DBT_ORACLE_WMS_SCHEMA | wms_raw | The schema where raw WMS data is stored. |
DBT_DUCKDB_PATH | ./flext_oracle_wms_dev.duckdb | Path for the local development database. |
DBT_POSTGRES_HOST | localhost | Host address for staging/prod Postgres. |
DBT_SCHEMA | wms_raw | Default schema for DBT transformations. |
Sources: dbt_project.yml:71-72, profiles.yml:13-14
Workflow & Client Integration
The FlextDbtOracleWmsClient orchestrates the flow between settings and execution. It initializes the Oracle WMS domain client using the provided settings and coordinates the extraction and transformation pipeline.
Initialization Flow
When a client is instantiated, it either uses an explicit settings object or fetches the global configuration. This configuration is then used to bootstrap the underlying FlextOracleWmsSettings for the domain-specific client.
The sequence shows the transition from global application settings to a validated domain client.
Sources: src/flext_dbt_oracle_wms/_utilities/client.py:24-35, src/flext_dbt_oracle_wms/_utilities/client.py:157-175
Governance & Maintenance
As defined in AGENTS.md, environment and settings management follows strict engineering laws:
- Zero-Debt Baseline: Config changes must not break tests; tests must read from the typed SSOT rather than hardcoding values.
- Fix Forward: Configuration clobbering is avoided by accepting the current state and applying surgical updates.
- Parametrization: All binaries and daemon-specific codes are parametrized through settings or templates; no hardcoded logic for specific environments is permitted in the codebase.
Sources: AGENTS.md:21-30, AGENTS.md:126-130
Conclusion
Environment and Settings Management in flext-dbt-oracle-wms ensures that the transformation pipeline is both flexible and robust. By centralizing configuration in Pydantic models and leveraging DBT's native profiling system, the project achieves environment parity while allowing for granular control over performance (via dbt_threads) and data integrity (via required_fields_per_entity).