Quick Start Guide

Relevant source files

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

• examples/01_basic_usage.py
• examples/run_example.sh
• examples/README.md
• CONTRIBUTING.md
• tests/README.md
• examples/03_production_setup.py

This guide provides a foundational overview for setting up and using flext-target-oracle, a Singer-compatible target for loading data into Oracle Databases. The system is built on the FLEXT ecosystem, utilizing railway-oriented programming for robust error handling and Pydantic for type-safe configurations.

The scope of this guide covers local environment setup, basic target initialization, and the processing of standard Singer messages (SCHEMA, RECORD, and STATE). Developers can use this guide to transition from a clean environment to a functional data loading pipeline.

Sources: examples/README.md:1-24, examples/01_basic_usage.py:1-25

Environment Setup

Before implementing the target, ensure your development environment meets the minimum requirements and the necessary infrastructure is available.

Prerequisites

• Python: Version 3.13+ is required.
• Oracle Database: A running instance (e.g., Oracle XE via Docker).
• Tools: Poetry for dependency management and Git for version control.

Sources: CONTRIBUTING.md:27-32, examples/README.md:28-40

Local Initialization

To get started locally, clone the repository and install the project in editable mode or via Poetry:

# Clone and install
git clone https://github.com/flext-sh/flext-target-oracle.git
cd flext-target-oracle
pip install -e .

# Start a local Oracle XE container for testing
docker run -d \
  --name oracle-xe \
  -p 1521:1521 \
  -e ORACLE_PASSWORD=oracle \
  gvenzl/oracle-xe:21-slim

Sources: CONTRIBUTING.md:36-45, examples/README.md:31-40

Target Configuration

The target uses FlextTargetOracleSettings for configuration. This class provides validation for connection parameters and operational behavior like batch sizes and loading methods.

Core Configuration Parameters

Parameter	Type	Default	Description
oracle_host	string	-	Hostname of the Oracle server.
oracle_port	integer	1521	Port for Oracle listener.
oracle_service_name	string	-	Oracle Service Name (e.g., "XE").
oracle_user	string	-	Database username.
oracle_password	string	-	Database password.
default_target_schema	string	-	Target schema for created tables.
batch_size	integer	100	Number of records per batch.
use_bulk_operations	boolean	True	Enables bulk DML operations.

Sources: examples/01_basic_usage.py:46-75, examples/03_production_setup.py:82-132

Operational Workflow

The target operates by receiving Singer messages via the process_singer_message method. This method routes messages to appropriate handlers based on the type field.

Message Processing Flow

The following diagram illustrates how the FlextTargetOracle interacts with incoming Singer messages to synchronize data with the database:

The target manages table creation (DDL) during SCHEMA messages and data ingestion (DML) during RECORD messages.

Sources: examples/01_basic_usage.py:136-180, examples/03_production_setup.py:255-300, CONTRIBUTING.md:105-125

Basic Implementation Example

A minimal implementation involves initializing the target with settings and passing message objects:

from flext_target_oracle import FlextTargetOracle, FlextTargetOracleSettings

# 1. Setup Settings
settings = FlextTargetOracleSettings(
    oracle_host="localhost",
    oracle_user="system",
    oracle_password="password",
    oracle_service_name="XE",
    default_target_schema="MY_DATA"
)

# 2. Initialize Target
target = FlextTargetOracle(settings)

# 3. Process a message (e.g., SCHEMA)
result = target.process_singer_message(schema_message)
if result.failure:
    print(f"Error: {result.error}")

Sources: examples/01_basic_usage.py:136-160, examples/run_example.sh:35-50

Testing and Verification

Validation of the setup can be performed using the built-in test suite or manual verification scripts.

Running Tests

The project includes unit and integration tests. Integration tests require a live Oracle database.

# Run all tests
make test

# Run only unit tests (no database required)
make test-unit

# Run integration tests
make test-integration

Sources: CONTRIBUTING.md:58-85, tests/README.md:31-45

Verifying Loaded Data

After running the target, users can verify the schema flattening and record insertion by querying the Oracle database directly:

• Flattening: Nested JSON objects in Singer records are converted into flat columns (e.g., address.city becomes ADDRESS_CITY).
• Audit Columns: The target automatically adds _SDC_EXTRACTED_AT and _SDC_LOADED_AT columns for tracking.

Sources: examples/run_example.sh:78-85, tests/README.md:72-85

Conclusion

The flext-target-oracle provides a type-safe, enterprise-ready approach to Oracle data loading. By following this guide, developers can establish a basic pipeline that handles schema evolution and high-volume data batches using standard Singer protocols. For advanced deployments involving custom indexes or production-grade error handling, refer to the Production Setup examples.

Sources: examples/README.md:120-130, examples/01_basic_usage.py:236-245