CLI Reference
Relevant source files
The following files were used as context for generating this wiki page:
The CLI (Command Line Interface) for flext-tap-oracle-oic provides a standardized entry point for interacting with the Oracle Integration Cloud (OIC) Singer tap. It adheres to the Singer protocol, supporting operations such as service discovery, connection testing, and full data extraction. The interface is built to be compatible with orchestration tools like Meltano through the flext-meltano integration layer.
Sources: src/flext_tap_oracle_oic/cli.py:1-15, pyproject.toml:68-70
Command Execution & Entry Points
The tap exposes two primary shell commands via its pyproject.toml configuration: flext-tap-oracle-oic and tap-oracle-oic. Both commands point to the FlextTapOracleOic.cli method, which handles argument parsing and service initialization.
Sources: pyproject.toml:68-70, src/flext_tap_oracle_oic/tap.py:388-390
Execution Flow
The CLI initialization follows a structured path from the shell command to the internal service logic.
The diagram illustrates the delegation from the entry point to the specific protocol actions based on command-line arguments.
Sources: src/flext_tap_oracle_oic/cli.py:31-78, src/flext_tap_oracle_oic/tap.py:339-354
Standard Singer Operations
The CLI supports the core Singer protocol flags required for automated data pipelines.
| Flag | Description | File Reference |
|---|---|---|
--discover | Generates a JSON catalog of available OIC streams and their schemas. | cli.py:53 |
--config FILE | Specifies the path to the JSON configuration file containing OIC credentials. | cli.py:54 |
--catalog FILE | Specifies the catalog file to filter or configure specific streams for extraction. | cli.py:55 |
--state FILE | Provides the state file for incremental syncs, allowing the tap to resume from a bookmark. | cli.py:56 |
--test | Custom extension to test the connection to the OIC API before running. | tap.py:350 |
Sources: src/flext_tap_oracle_oic/cli.py:50-57, src/flext_tap_oracle_oic/tap.py:339-354
Configuration Management
The CLI utilizes environment variables and JSON configuration files to manage sensitive credentials and operational settings. The configuration is validated using Pydantic models to ensure required fields like oauth_client_id and oic_url are present.
Environment Variables
Variables are prefixed with FLEXT_TAP_ORACLE_OIC_ as defined in the settings module.
| Environment Variable | Description | Default |
|---|---|---|
TAP_ORACLE_OIC_OIC_URL | The base URL for the OIC instance. | Mandatory |
TAP_ORACLE_OIC_OAUTH_CLIENT_ID | OAuth2 Client ID for authentication. | Mandatory |
TAP_ORACLE_OIC_OAUTH_CLIENT_SECRET | OAuth2 Client Secret (masked in logs). | Mandatory |
TAP_ORACLE_OIC_OAUTH_TOKEN_URL | URL to retrieve the OAuth2 access token. | Mandatory |
TAP_ORACLE_OIC_INCLUDE_EXTENDED | Boolean flag to include metadata-heavy infrastructure streams. | False |
Sources: src/flext_tap_oracle_oic/settings.py:22-55, src/flext_tap_oracle_oic/tap.py:316-337
Initialization Logic
Before executing a command, the tap performs a configuration validation check.
The sequence diagram shows the validation gate that prevents execution if mandatory parameters (URL, OAuth credentials) are missing.
Sources: src/flext_tap_oracle_oic/tap.py:214-236, src/flext_tap_oracle_oic/tap.py:326-337
Service Commands and Exit Codes
The CLI returns standard exit codes to signal success or failure to the parent process (e.g., Meltano or Cron).
- 0: Success. The requested operation (discovery, test, or run) completed without errors.
- 1: Failure. Occurs during configuration errors, connection timeouts, or API authentication failures.
def main() -> int:
"""Run Oracle OIC tap with proper error handling."""
exit_code = _validate_and_setup_config()
if exit_code != 0:
return exit_code
config_typed = t.json_dict_adapter().validate_python(_build_config_from_env())
tap = FlextTapOracleOic(settings=config_typed)
try:
return _execute_tap_command(tap)
except c.Meltano.SINGER_SAFE_EXCEPTIONS as e:
logger.exception("Oracle OIC tap execution failed")
return 1
Sources: src/flext_tap_oracle_oic/tap.py:301-313, src/flext_tap_oracle_oic/constants.py:73-77
Conclusion
The flext-tap-oracle-oic CLI serves as a robust interface for the Singer ecosystem, providing mandatory protocol compliance while extending functionality with connection testing and environment-aware configuration. Its integration with flext-meltano ensures that it can be seamlessly orchestrated in modern data engineering stacks.