Settings & Environment Variables
Relevant source files
The following files were used as context for generating this wiki page:
The configuration management system in FLEXT DB Oracle is built upon the Clean Architecture's infrastructure layer, utilizing Pydantic-based validation to ensure type safety and enterprise-grade reliability. The primary contract for this configuration is the FlextDbOracleSettings class, which manages connection parameters, authentication, and pool behavior for Oracle database integrations.
Sources: src/README.md:27-28, src/flext_db_oracle/settings.py:16-19
This system supports multiple configuration sources, including direct instantiation, environment variables with specific prefixes (e.g., ORACLE_ and FLEXT_TARGET_ORACLE_), and Oracle connection URLs. It acts as a single source of truth for the FlextDbOracleApi and other core services.
Sources: src/flext_db_oracle/settings.py:126-160, tests/unit/test_api.py:53-56
Configuration Architecture
The architecture follows a hierarchical structure where raw configuration data from external sources is validated and transformed into a typed FlextDbOracleSettings object. This object is then consumed by the Application Layer.
The flow shows how configuration sources are aggregated, validated, and distributed to the core application components.
Sources: src/README.md:46-60, src/flext_db_oracle/settings.py:126-174
Environment Variable Resolution
The project uses specific prefixes to identify relevant environment variables. The primary prefix is ORACLE_, but the system also prioritizes FLEXT_TARGET_ORACLE_ variables for enterprise ecosystem integration.
Resolution Logic
- Prefix Filtering: The system searches for variables starting with the requested prefix (default
ORACLE_). - Mapping: Environment names are mapped to field names based on a defined mapping (e.g.,
ORACLE_HOSTmaps tohost). - Prioritization: When using the
ORACLE_prefix, values found underFLEXT_TARGET_ORACLE_take precedence and will update or overwrite the base values.
Sources: src/flext_db_oracle/settings.py:126-153, tests/unit/test_models.py:349-380
Configuration Options & Parameters
The FlextDbOracleSettings class defines several fields with specific validation rules and default values.
| Field | Type | Default | Description |
|---|---|---|---|
host | str | localhost | Oracle database host address. |
port | PortNumber | 1521 | Oracle database listener port (Range: 1-65535). |
service_name | str | XEPDB1 | Oracle service name (Upper-cased, max 128 chars). |
username | str | system | Oracle database username. |
password | FlextDbOraclePassword | "" | Database password, handled as a secret type. |
timeout | PositiveInt | 30 | Connection timeout in seconds. |
pool_min | PositiveInt | 1 | Minimum connection pool size. |
pool_max | PositiveInt | 10 | Maximum connection pool size. |
sid | str | None | None | Oracle SID for legacy connections. |
ssl_cert_file | str | None | None | Path to SSL certificate file. |
Sources: src/flext_db_oracle/settings.py:32-94, tests/unit/test_models.py:284-295
Validation & Business Rules
The settings module implements strict validation logic beyond simple type checking to ensure connection strings are viable before attempting a database connection.
Business Rule Constraints
- Host/Username: Cannot be empty or purely whitespace.
- Port Range: Must be between 1 and 65535.
- Service Identifier: Either
service_nameorsidmust be provided. - SSL Configuration: If
ssl_cert_fileis provided without a specificssl_server_cert_dn, the file path is reused as the DN for compatibility.
This diagram illustrates the internal validation lifecycle of a settings object when initialized from environment variables.
Sources: src/flext_db_oracle/settings.py:155-165, tests/unit/test_api.py:165-177
URL-Based Configuration
Configurations can be derived from standard Oracle connection URLs using the from_url method. Supported schemes include oracle and oracle+oracledb.
URL Parsing Logic
- Scheme: Must be
oracleororacle+oracledb. - Path/Query: The
service_nameis extracted from the URL path (e.g.,/service) or theservice_namequery parameter. - Credentials: Usernames and passwords are automatically unquoted.
Sources: src/flext_db_oracle/settings.py:177-203, tests/unit/test_api.py:188-195
Dependency Integration
The configuration system relies on several key dependencies defined in the project structure:
- flext-core: Provides the
FlextSettingsBaseand Result patterns (r). - pydantic: Handles the underlying schema validation and environment source processing.
- oracledb: Influences connection parameters and default identifiers.
Sources: pyproject.toml:25-29, src/flext_db_oracle/settings.py:12-14
Summary
Settings & Environment Variables in FLEXT DB Oracle provide a robust, validated, and multi-sourced configuration foundation. By enforcing business rules and supporting flexible environment resolution (including ecosystem-wide FLEXT_TARGET_ORACLE_ overrides), the system ensures that infrastructure parameters are correct before they reach the core Oracle service facade.
Sources: src/README.md:27-28, src/flext_db_oracle/settings.py:126-153