Basic Usage & Quickstart
Relevant source files
The following files were used as context for generating this wiki page:
FLEXT DB Oracle is an enterprise-grade Oracle database integration library designed for high-level database operations within the FLEXT ecosystem. It follows Clean Architecture principles to provide a robust, type-safe interface for managing connections, executing queries, and introspecting Oracle schemas. The library is built on top of the oracledb driver and integrates seamlessly with FLEXT Core patterns such as Railway-oriented programming (r[T]) for error handling and Pydantic for configuration validation.
Sources: src/README.md:6-14, README.md:7-9, pyproject.toml:22-26
Core Components & Architecture
The library is organized into distinct layers to maintain a clean separation of concerns. The Application Layer provides the primary entry points for developers, while the Infrastructure and Foundation layers handle resource management and core utilities.
Primary Classes
| Class | Description |
|---|---|
FlextDbOracleApi | The main service facade providing high-level database operations (querying, schema fetching). |
FlextDbOracleSettings | Configuration management class with Pydantic validation for connection parameters. |
FlextDbOracleServices | Internal service facade for statement building, DDL generation, and low-level execution. |
Sources: src/README.md:18-35, tests/unit/test_api.py:38-48, tests/unit/test_services.py:35-43
Service Interaction Flow
The following diagram illustrates how a user interacts with the FlextDbOracleApi to initialize a connection and execute a query.
Configuration Management
Configuration is handled by FlextDbOracleSettings, which validates required parameters such as host, port, and credentials. The library supports loading configuration from environment variables or direct instantiation.
Connection Parameters
| Parameter | Type | Default / Requirement | Description |
|---|---|---|---|
host | str | Required | The Oracle database host address. |
port | int | 1521 | The listener port for the database. |
username | str | Required | The database user for authentication. |
password | SecretStr | Required | The authentication password (masked in logs). |
service_name | str | Required | The Oracle Service Name (e.g., XEPDB1). |
Sources: tests/unit/test_services.py:45-55, tests/unit/test_api.py:40-50, tests/unit/README.md:95-108
Environment Variables
For integration and production environments, settings are typically provided via prefixed environment variables:
FLEXT_TARGET_ORACLE_HOSTFLEXT_TARGET_ORACLE_PORTFLEXT_TARGET_ORACLE_USERNAMEFLEXT_TARGET_ORACLE_PASSWORDFLEXT_TARGET_ORACLE_SERVICE_NAME
Sources: tests/README.md:162-170, tests/e2e/README.md:73-80
Basic Database Operations
The FlextDbOracleApi provides methods for executing SQL and retrieving data. All methods return a Result object (r[T]), requiring the caller to check for success before accessing values.
Querying Data
The query and query_one methods are used for DQL operations. The library automatically handles parameter binding to prevent SQL injection.
# Initialization
settings = FlextDbOracleSettings(
host="localhost",
port=1521,
username="app_user",
password="password",
service_name="XEPDB1"
)
api = FlextDbOracleApi(settings)
# Context management for connection
with api:
result = api.query("SELECT * FROM USERS WHERE ID = :id", {"id": 101})
if result.success:
rows = result.value
# Process rows
Sources: tests/unit/test_api.py:100-120, tests/e2e/README.md:144-165
Schema Introspection
The API provides high-level methods to explore the database structure without manual SQL:
fetch_schemas(): Lists available database schemas.fetch_tables(schema): Lists tables within a specific schema.fetch_columns(table, schema): Lists column definitions for a table.
Sources: tests/unit/test_api.py:164-185, tests/unit/test_services.py:125-140
DDL & Statement Building
The FlextDbOracleServices layer includes utilities for generating Oracle-compliant SQL for data definition and manipulation.
Type Mapping (Singer to Oracle)
The service layer provides automatic conversion from Singer JSON Schema types to Oracle SQL types:
string->VARCHAR2(4000)integer->NUMBER(38)boolean->NUMBER(1)date-time->TIMESTAMP
Sources: tests/unit/test_services.py:100-115
Conclusion
FLEXT DB Oracle provides a standardized, enterprise-grade way to interact with Oracle databases by abstracting low-level driver details into clean service facades. By utilizing FlextDbOracleApi for high-level workflows and FlextDbOracleServices for schema management and DDL generation, developers can build robust database integrations that adhere to FLEXT's quality and architectural standards.
Sources: src/README.md:139-145, tests/README.md:12-25