Service Layer
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Service Layer in flext-target-oracle acts as the intermediary orchestration tier that bridges the Singer-compliant Target interface with the underlying Oracle database operations. It is designed following Clean Architecture principles and Railway-Oriented Programming (ROP) to ensure type safety and robust error handling through the use of p.Result types. Sources: CONTRIBUTING.md:144-150, src/flext_target_oracle/_utilities/services.py
This layer encapsulates specialized logic for connection management, schema validation, batching, and record transformation. By isolating these concerns into focused service objects, the system maintains a high degree of modularity and testability, allowing the Loader and Target classes to coordinate complex data loading workflows without direct coupling to low-level database drivers. Sources: src/flext_target_oracle/_utilities/services.py:10-15, src/flext_target_oracle/_utilities/loader.py:25-30
Service Architecture
The architecture relies on four primary service components that implement specific protocols for handling the lifecycle of a Singer data stream. All services ingest FlextTargetOracleSettings and a FlextDbOracleApi instance to perform their duties. Sources: src/flext_target_oracle/_utilities/services.py:10-142
Service Components Overview
| Service Class | Responsibility | Key Operation |
|---|---|---|
FlextTargetOracleConnectionService | Validates connectivity and retrieves metadata. | test_connection() |
FlextTargetOracleSchemaService | Ensures target tables and schemas are valid. | ensure_table_exists() |
FlextTargetOracleBatchService | Manages in-memory buffers for bulk loading. | flush_all_batches() |
FlextTargetOracleRecordService | Transforms and validates individual record payloads. | transform_record() |
Sources: src/flext_target_oracle/_utilities/services.py:13-142
Dependency Flow
The following diagram illustrates how the services interact with the core configuration and the Oracle API to process data.
Core Service Details
Connection Service
The FlextTargetOracleConnectionService is responsible for normalized connection modeling. It uses the fetch_tables method of the Oracle API to verify that the configured user has appropriate access to the target schema. Sources: src/flext_target_oracle/_utilities/services.py:13-39
- test_connection(): Executes a probe by listing tables in the
default_target_schema. Sources: src/flext_target_oracle/_utilities/services.py:32-39 - get_connection_info(): Returns a
m.TargetOracle.OracleConnectionModelderived from the application settings. Sources: src/flext_target_oracle/_utilities/services.py:27-30
Batch and Record Services
The BatchService maintains a defaultdict of lists to buffer SingerRecordMessage objects per stream. This allows the target to perform high-performance bulk inserts instead of row-by-row processing. Sources: src/flext_target_oracle/_utilities/services.py:69-102
The RecordService handles the "Flattening" and "Mapping" logic. It filters out columns defined in ignored_columns and renames keys based on the column_mappings configuration. Sources: src/flext_target_oracle/_utilities/services.py:105-142
Error Handling in Services
The service layer utilizes a specialized exception hierarchy defined in FlextTargetOracleExceptions. Errors are categorized to provide specific context such as correlation_id, stream_name, or table_name. Sources: src/flext_target_oracle/_utilities/errors.py:45-135
Exception Types
| Exception Class | Usage Scenario | Derived Context |
|---|---|---|
OracleConnectionError | Failures during test_connection or initial handshake. | dsn, user, service_name |
ProcessingError | Failures during record transformation or batch flushing. | record_count, operation |
SchemaError | Failures during table creation or DDL validation. | schema_hash, validation_errors |
Sources: src/flext_target_oracle/_utilities/errors.py:65-135
CLI Orchestration Service
The FlextTargetOracleCliService serves as the entry point for command-line interactions. it maps incoming arguments to the corresponding command factories. Sources: src/flext_target_oracle/_utilities/cli.py:15-53
- validate: Triggers the
ConnectionServiceto verify settings. - load: Initializes the
Loaderand services for standard Singer execution. - about: Returns metadata about the target implementation.
def run_cli(self, args: t.StrSequence | None = None) -> p.Result[str]:
"""Dispatch CLI args to the appropriate command."""
argv = args if args is not None else sys.argv[1:]
command_name = argv[0]
if command_name == "validate":
return m.TargetOracle.OracleTargetCommandFactory.create_validate_command(None).execute()
# ... logic for other commands
Sources: src/flext_target_oracle/_utilities/cli.py:30-48
Summary
The Service Layer provides a robust framework for managing the complexities of Oracle data loading. By separating connection, schema, batching, and transformation logic into distinct services, flext-target-oracle achieves a maintainable architecture that adheres to FLEXT's design principles of Railway-Oriented Programming and type safety. Sources: CONTRIBUTING.md:151-155, src/flext_target_oracle/_utilities/services.py:10-15