Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
The flext-tap-oracle project is a modern Singer Tap designed for Oracle Databases, built upon the FLEXT framework. It facilitates the extraction of data from Oracle instances using the Singer specification, integrating deeply with flext-core, flext-db-oracle, and flext-meltano to provide a robust, enterprise-grade ETL solution.
This guide provides the necessary technical foundation to configure, initialize, and execute the tap. It covers environment setup, connection requirements, and the primary execution modes: Discovery and Sync.
Sources: README.md:9-11, pyproject.toml:23-35, src/flext_tap_oracle/rules.json:11-20
Prerequisites and Installation
The tap requires Python 3.13+ and relies on several core FLEXT libraries for database interaction and observability.
System Requirements
- Python: Version 3.13 is strictly required.
- Dependencies: The tap integrates with
flext-db-oraclefor native Oracle connection pooling andflext-meltanofor Singer protocol abstractions.
Sources: pyproject.toml:34-45, src/flext_tap_oracle/rules.json:20
Installation
The package can be installed via standard Python package managers. It exposes two primary CLI entry points: flext-tap-oracle and tap-oracle.
pip install flext-tap-oracle
Sources: pyproject.toml:135-137
Configuration
Configuration is managed through Pydantic-validated settings, supporting environment variables with the prefix FLEXT_TAP_ORACLE_.
Connection Parameters
To establish a connection, you must provide either a service_name or a sid.
| Parameter | Type | Default | Description |
|---|---|---|---|
host | String | localhost | Oracle database host address. |
port | Integer | 1521 | Oracle TNS listener port. |
user | SecretStr | - | Database username. |
password | SecretStr | - | Database password. |
service_name | String | - | Oracle service name. |
batch_size | Integer | 1000 | Records per extraction batch. |
Sources: src/flext_tap_oracle/settings.py:27-58, src/flext_tap_oracle/rules.json:62-75
Validation Flow
The tap performs eager validation of business rules before initiating database connections.
Operation Modes
The tap operates in two primary modes via the CLI: Discovery and Sync.
Discovery Mode
Discovery introspects the Oracle database to identify available tables and generate a Singer catalog. By default, it explores the USER schema.
- Class:
FlextTapOracleDiscoverCommand - Output: A JSON catalog file representing the database schema.
Sync Mode
Sync mode performs the actual data extraction. It leverages FlextDbOracleApi for optimized queries and handles type conversion from Oracle-native types (like CLOB or TIMESTAMP) to Singer-compatible strings.
- Class:
FlextTapOracleSyncCommand - Streams: Managed by
FlextTapOracleStreams, which uses system views to estimate row counts for progress monitoring.
Sources: src/flext_tap_oracle/tap.py:79-130, src/flext_tap_oracle/streams.py:23-50
Execution Summary
Upon completion, the tap provides detailed execution statistics including duration, record counts, and performance metrics.
| Metric | Field | Description |
|---|---|---|
| Volume | total_records | Total number of rows extracted. |
| Speed | avg_records_per_second | Calculated processing throughput. |
| Latency | oracle_query_time | Time spent executing SQL in the database. |
| Status | failed_streams | List of streams that encountered errors. |
Sources: src/flext_tap_oracle/models.py:84-125
Conclusion
Getting started with flext-tap-oracle involves configuring the Pydantic-based settings, validating the Oracle connection via the discovery command, and finally executing a sync to extract data. The tap's architecture ensures that database-specific complexities, such as Oracle type mapping and connection pooling, are handled transparently by the underlying FLEXT ecosystem.