Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
The development setup for the flext-target-oracle project provides a standardized environment for building, testing, and contributing to the Singer Target for Oracle Database. It relies on a containerized Oracle environment and Python-based tooling to ensure consistency across development workstations.
The setup covers environment provisioning, dependency management via Poetry, and automated testing procedures using Docker. This ensures that developers can verify DDL/DML operations against a real Oracle instance as part of the Testing Strategy.
Sources: CONTRIBUTING.md:10-14, README.md:9-12
🛠️ Environment Prerequisites
To contribute to or develop for flext-target-oracle, the following core components are required:
- Python 3.13+: The project is strictly typed and uses modern Python features.
- Docker and Docker Compose: Required for running the Oracle XE database container.
- Poetry: Used for dependency management and environment isolation.
- Git: For version control and repository management.
Sources: CONTRIBUTING.md:46-51, pyproject.toml:50-50, tests/README.md:27-31
🏗️ Initial Workspace Setup
The project uses make verbs to abstract complex setup tasks. The following sequence initializes the development environment:
- Clone and Enter Repository:
git clone https://github.com/flext-sh/flext-target-oracle.git cd flext-target-oracle - Install Dependencies: Use
make dev-setupor manual poetry commands.make dev-setup # OR poetry install --all-extras pip install -r requirements-test.txt - Oracle Database Provisioning: Start the local Oracle container.
make oracle-start
Sources: CONTRIBUTING.md:55-76, examples/README.md:43-52
Dependency Structure
The project relies on several flext-* ecosystem libraries and managed development dependencies.
| Category | Key Dependencies |
|---|---|
| Core Integration | flext-core, flext-db-oracle, flext-cli |
| Linting/Formatting | ruff, black, isort, mypy |
| Testing | pytest, pytest-cov, pytest-mock, pytest-xdist |
| Documentation | mkdocs, mkdocs-material, mkdocstrings |
Sources: pyproject.toml:25-38, pyproject.toml:68-158
🧪 Testing Environment
The testing architecture is categorized by dependency levels, using markers to separate fast unit tests from slower database-dependent tests.
The diagram shows the isolation between unit tests (mocked) and integration/E2E tests (requiring Docker).
Sources: CONTRIBUTING.md:83-93, tests/README.md:12-23
Running Tests
| Command | Purpose | Requirement |
|---|---|---|
make test-unit | Fast execution of logic tests | None |
make test-integration | Validates DDL/DML against Oracle | Docker Running |
make test | Full suite including Singer workflows | Docker Running |
make coverage | Generates HTML/Terminal reports | None |
Sources: CONTRIBUTING.md:97-110, tests/README.md:37-45
🐳 Oracle Container Management
The test suite automatically manages an Oracle XE container lifecycle using Docker Compose. The container is configured to create a FLEXT_TEST schema with appropriate permissions during startup.
The sequence illustrates the automated lifecycle of the Oracle container during testing.
Sources: tests/README.md:65-73, examples/run_example.sh:17-21
Connection Parameters
Default development environment variables for the Oracle connection:
- Host:
localhost - Port:
1521 - Service:
XE - User:
FLEXT_TEST - Password:
test_password
Sources: tests/README.md:103-109, examples/run_example.sh:26-32
📝 Code Quality and Standards
The project enforces strict quality gates through pre-commit hooks and make commands. Developers must ensure code passes all automated checks before submitting pull requests.
# Individual checks
make format # Black + Ruff formatting
make lint # Ruff linting
make type-check # Mypy static analysis
make check # Run all quality checks
Sources: CONTRIBUTING.md:143-157, pyproject.toml:390-410
Architecture Principles
- Railway-Oriented Programming: The
rpattern is used for error handling. - Strict Typing: All code must be fully typed (enforced by
mypyandpyright). - Managed Config: Configuration is handled via Pydantic models in
src/flext_target_oracle/settings.py. - Abstraction: SQL is never generated directly in the target; it must use
FlextDbOracleApi.
Sources: CONTRIBUTING.md:175-188, CONTRIBUTING.md:204-208
🚀 Summary of Significance
The development setup of flext-target-oracle is designed to provide a "zero-debt" baseline, allowing developers to immediately engage with the code via a pre-configured Docker stack and automated test suite. By strictly adhering to the make contract and flext-quality-gates, the project maintains high standards for enterprise data loading reliability.
Sources: README.md:24-27, README.md:31-33