Basic Coverage & Unit Specs
Relevant source files
The following files were used as context for generating this wiki page:
The "Basic Coverage & Unit Specs" represent the foundational validation layer for the flext-dbt-oracle adapter. This suite ensures that the core components—ranging from configuration management and connection string generation to architectural governance—function according to the project's strict engineering laws. The primary focus is on verifying that the FlextDbtOracleSettings and associated connection managers adhere to Oracle-specific requirements while maintaining compatibility with the dbt-core framework.
This specification serves as the ground truth for adapter behavior, ensuring that configuration changes do not break existing contracts and that all components are correctly initialized. It covers initialization, type safety, validation logic, and the structural integrity of the package.
Sources: tests/unit/test_basic.py, rules.json, AGENTS.md:15-30
Configuration & Settings Validation
The configuration system is centered around FlextDbtOracleSettings, which manages Oracle-specific connection parameters and performance tuning. Validation logic ensures that critical fields like host, username, and password are handled correctly, often applying default values when explicit ones are missing.
Validation Logic and Constraints
The system enforces strict typing and range validation for performance-related settings such as pool sizes and timeouts. For instance, pool_max_size must be greater than or equal to pool_min_size, and port numbers must be positive integers.
The diagram above shows the flow from raw input to a validated settings object, highlighting the points where defaults are applied and validations are enforced.
Sources: tests/unit/_config_parts/validation.py:15-85, rules.json:30-45
Key Configuration Parameters
| Parameter | Type | Default/Constraint | Description |
|---|---|---|---|
oracle_host | str | Applied if missing | The hostname of the Oracle database server. |
oracle_port | int | 1521 (typically) | The listener port for the Oracle database. |
protocol | Literal['tcp', 'tcps'] | tcp | The network protocol used for the connection. |
materialization | Enum | table | dbt materialization type (table, view, incremental, snapshot). |
pool_min_size | int | >= 1 | Minimum number of connections in the pool. |
pool_max_size | int | >= pool_min_size | Maximum number of connections in the pool. |
Sources: tests/unit/_config_parts/validation.py:87-128, tests/unit/test_connections.py:17-25
Connection Management
Connection management transforms settings into Oracle-compatible connection strings and data structures. The adapter supports two primary identification methods for Oracle databases: Service Names and SIDs.
DSN and Connection String Generation
The logic for generating a Data Source Name (DSN) varies based on whether a service_name or sid is provided. Service names typically use a forward slash (/) separator, while SIDs use a colon (:).
Exporting Configurations
The settings object can be exported into various formats required by different layers of the application:
- Connection Config: A dictionary of core credentials (host, port, user, etc.).
- Oracle Config: Specific settings for the underlying
flext-db-oraclelibrary. - Performance Settings: A subset focusing on pooling and timeouts.
- Dbt Settings: Metadata like schema and materialization strategy for dbt-core.
Sources: tests/unit/_config_parts/connection.py:75-125
Module Governance & Architecture
The project enforces strict architectural "laws" through automated governance tests. These tests ensure the codebase remains maintainable and follows specific design patterns, such as avoiding global state and maintaining a clean public API.
Governance Rules
- No Module-Level Loggers: Loggers must not be defined at the top level of package modules to prevent initialization side effects.
- No Top-Level Functions: Logic should be encapsulated within classes or specific service structures to maintain a consistent Object-Oriented approach.
- Lazy Imports: The project utilizes a lazy loading mechanism (
flext_core.lazy) for exports to improve startup performance and manage dependencies effectively.
Implementation Details
The implementation includes helper classes for managing dbt relations and table metadata. The OracleTableAdapter provides a consistent interface for mapping dbt's internal representation of tables to Oracle's schema and table structures.
OracleTableAdapter Example
The adapter manages the concatenation of schema and table names into a relation_name and provides metadata exports.
# From tests/unit/test_impl.py
adapter = m.DbtOracle.OracleTableAdapter(
schema_name="HR",
table_name="EMPLOYEES",
)
assert adapter.relation_name == "HR.EMPLOYEES"
meta = adapter.to_metadata()
# meta: {"schema": "HR", "table": "EMPLOYEES", "relation": "HR.EMPLOYEES"}
Sources: tests/unit/test_impl.py:15-35
Summary
The "Basic Coverage & Unit Specs" ensure that the flext-dbt-oracle package is built on a stable, validated foundation. By enforcing strict configuration validation, clear connection logic, and rigorous architectural governance, the project guarantees that the adapter behaves predictably in diverse Oracle environments. This foundational layer is critical for the "Fix Forward" and "SSOT" (Single Source of Truth) principles defined in the project's engineering core.