Data Models & Validations

Relevant source files

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

• src/flext_db_oracle/models.py
• src/flext_db_oracle/settings.py
• src/flext_db_oracle/api.py
• tests/unit/test_models.py
• tests/unit/test_services.py
• src/README.md

Introduction

The Data Models & Validations module within flext-db-oracle provides a robust, type-safe framework for representing Oracle database entities, connection states, and query results. Built upon the flext-core ecosystem, these models utilize Pydantic v2 for strict schema validation, ensuring that data flowing between the application layer and the Oracle database remains consistent and valid.

This module encompasses domain entities such as Table, Column, and Schema, as well as operational models like ConnectionStatus and QueryResult. It integrates directly with the Application Layer to provide structured data for introspection, DDL generation, and query execution.

Sources: src/flext_db_oracle/models.py:1-25, src/README.md:10-35

Core Domain Models

The domain models represent the structural components of an Oracle database. These are organized under the DbOracle namespace and inherit from m.Entity to support domain-driven design patterns within the FLEXT ecosystem.

Database Schema Structure

The hierarchy follows standard relational database nesting: a Schema contains multiple Table objects, which in turn contain Column definitions.

Sources: src/flext_db_oracle/models.py:270-335

Model Definitions

Class	Purpose	Key Fields
Table	Represents an Oracle table metadata.	name, owner, columns
Column	Represents an Oracle column and its constraints.	data_type, nullable, primary_key
Schema	Represents a database schema/user container.	name, tables
ColumnMetadata	Lightweight typed column payload for introspection.	name, data_type, nullable

Sources: src/flext_db_oracle/models.py:44-51, src/flext_db_oracle/models.py:270-335

Operational and Status Models

Beyond structural metadata, the module provides models to track the live state of the database integration.

Connection Monitoring

The ConnectionStatus model is used by the FlextDbOracleApi to report on the health and performance of the current connection. It includes computed fields for health checks and automated serialization for JSON reporting.

Query Execution Results

The QueryResult model encapsulates the output of SQL operations. It tracks row data, column names, execution timing, and performance metrics. It includes a custom validator to ensure that the number of values in each row matches the defined column count.

Sources: src/flext_db_oracle/models.py:157-235, tests/unit/test_models.py:148-185

Validation Logic

Validations are enforced at the model level using Pydantic model_validator and field_validator hooks.

Performance Thresholds

The system categorizes database operations into performance tiers based on execution time thresholds defined in constants.py.

Rating	Query Threshold (ms)	Connection Threshold (s)
Excellent	< 100ms	< 0.1s
Good	< 500ms	< 0.5s
Acceptable	< 1000ms	< 1.0s
Slow	>= 1000ms	>= 1.0s

Sources: src/flext_db_oracle/models.py:100-115, src/flext_db_oracle/models.py:210-225, tests/unit/test_models.py:73-88

Structural Validation Snippet

@u.model_validator(mode="after")
def validate_query_result_consistency(self) -> FlextDbOracleModels.DbOracle.QueryResult:
    """Validate query result consistency."""
    if len(self.rows) != self.row_count:
        self.row_count = len(self.rows)
    if self.rows and self.columns:
        for row in self.rows:
            if len(row.values) != len(self.columns):
                msg = f"Row length {len(row.values)} doesn't match column count {len(self.columns)}"
                raise ValueError(msg)
    return self

Sources: src/flext_db_oracle/models.py:240-252

Command Models for Dispatcher

For implementations using the command dispatcher pattern (enabled via FLEXT_DB_ORACLE_ENABLE_DISPATCHER), specific command models are defined to encapsulate parameters for database actions.

• ExecuteQueryCommand: Wraps SQL and bind parameters for SELECT queries.
• GetTablesCommand: Used for schema introspection filtering by schema_name.
• ExecuteManyCommand: Handles batch DML operations with a list of parameter sets.

Sources: src/flext_db_oracle/models.py:365-410, tests/unit/test_api.py:105-120

Conclusion

The Data Models & Validations module ensures that flext-db-oracle maintains high data integrity by defining clear boundaries and structures for Oracle interactions. By combining structural metadata with operational state tracking and automated performance tiering, it provides a comprehensive foundation for building reliable enterprise database integrations.