Oracle Target Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Oracle Target Configuration provides a type-safe, validated framework for managing connection parameters, data loading strategies, and schema materialization rules within the flext-target-oracle project. It ensures that Singer-formatted data is correctly transformed and loaded into an Oracle database while adhering to enterprise performance and security standards.
The configuration system is built upon Pydantic models and FLEXT core patterns, supporting environment variable overrides (prefixed with FLEXT_TARGET_ORACLE_), complex validation through business rules, and integration with Meltano projects.
Sources: src/flext_target_oracle/settings.py:12-21, examples/meltano_integration/meltano.yml:18-24
Configuration Architecture
The configuration architecture is divided into runtime settings, connection models, and validation logic. The primary entry point is FlextTargetOracleSettings, which inherits from FlextSettingsBase. This class manages the lifecycle of configuration from loading to validation and conversion into low-level connection parameters.
Configuration Data Flow
The following diagram illustrates how configuration is loaded, validated, and utilized by the Oracle Target.
The data flow ensures that any missing required fields or invalid business logic (e.g., commit intervals exceeding batch sizes) are caught before a database connection is attempted.
Sources: src/flext_target_oracle/settings.py:136-150, src/flext_target_oracle/_models/commands.py:84-100, src/flext_target_oracle/_utilities/errors.py:65-72
Connection Settings
Connection settings define how the target interacts with the Oracle instance, including host details, credentials, and pooling parameters.
| Option | Type | Default | Description |
|---|---|---|---|
oracle_host | str | localhost | Oracle database hostname or IP. |
oracle_port | int | 1521 | Database listener port. |
oracle_service_name | str | XE | Oracle service name or SID. |
oracle_user | SecretStr | (Empty) | Database username (protected). |
oracle_password | SecretStr | (Empty) | Database password (protected). |
transaction_timeout | int | 30 | Timeout in seconds for transactions. |
autocommit | bool | False | Enable/disable auto-commit. |
Sources: src/flext_target_oracle/settings.py:28-58, src/flext_target_oracle/_models/settings.py:12-34
Loading and Storage Strategy
The target supports multiple modes for materializing data into Oracle tables. These strategies allow users to optimize for performance (Bulk operations) or compatibility (Flattened vs. JSON).
Storage Modes
- Flattened: Singer records are unnested and mapped to individual columns in a relational table.
- JSON: The entire record payload is stored in a single column (default name
DATA) using Oracle's JSON capabilities.
Load Methods
Loading behavior is controlled by the load_method and sdc_mode settings.
Schema and Table Management
Configuration allows fine-grained control over how destination tables are named and structured.
- Naming Conventions: Tables are derived from stream names, with optional
table_prefixandtable_suffix. Stream names are normalized (replacing.and-with_) and converted to uppercase. - Column Ordering: Strategies can be applied to generated DDL, such as alphabetical ordering or priority-based rules (e.g., Primary Keys first).
- Custom Indexes: Users can define per-stream Oracle index definitions via the
custom_indexesmapping.
Sources: src/flext_target_oracle/settings.py:110-134, src/flext_target_oracle/_protocols/base.py:145-152
Configuration Validation
Validation is performed at both the Pydantic level (type checking) and the business rule level. The validate_business_rules method ensures the configuration is logically sound for Oracle operations.
Validation Sequence
Metadata and About Command
The target provides metadata about its capabilities through the about command, which returns information in JSON or Text format.
| Capability | Description |
|---|---|
| Name | flext-target-oracle |
| Description | Singer target for Oracle loading |
| Protocols | Singer, FLEXT 1.0.0 |
Sources: src/flext_target_oracle/_models/commands.py:32-45
Error Contextualization
When configuration or connection failures occur, the system uses a structured exception hierarchy to provide detailed diagnostic information.
class FlextTargetOracleErrorMetadata(m.FlexibleInternalModel):
"""Structured metadata attached to Oracle target error responses."""
code: Annotated[str, u.Field(description="Canonical error code")]
context: Annotated[t.JsonMapping | None, u.Field(description="Structured context")] = None
correlation_id: Annotated[str | None, u.Field(description="Correlation ID")] = None
These errors include Oracle-specific fields like service_name, dsn, and wallet_location to assist in troubleshooting database connectivity issues.
Sources: src/flext_target_oracle/_utilities/errors.py:22-35, src/flext_target_oracle/_utilities/errors.py:72-88
Summary
Oracle Target Configuration serves as the foundation for the flext-target-oracle loader. By centralizing connection management, storage strategies, and table naming rules into a validated, type-safe system, it allows developers to build robust ETL pipelines. The integration of bulk loading methods and custom index support ensures that the configuration can be tuned for high-performance enterprise Oracle environments.