{"id":9646,"library":"dbt-oracle","title":"dbt-oracle Adapter","description":"dbt-oracle is a dbt (data build tool) adapter that enables dbt to connect to and transform data within Oracle Autonomous Database. It allows users to leverage dbt's powerful data transformation capabilities on their Oracle data warehouses. The library is actively maintained, with frequent patch releases within minor versions following dbt-core's release cadence. The current version is 1.10.0.","status":"active","version":"1.10.0","language":"en","source_language":"en","source_url":"https://github.com/oracle/dbt-oracle","tags":["dbt","oracle","database","etl","data build tool","data transformation"],"install":[{"cmd":"pip install dbt-oracle","lang":"bash","label":"Install dbt-oracle"}],"dependencies":[{"reason":"Core dbt functionality; version compatibility is strict.","package":"dbt-core","optional":false},{"reason":"The Python driver for connecting to Oracle databases.","package":"oracledb","optional":false}],"imports":[],"quickstart":{"code":"import os\n\n# Configure dbt profile in profiles.yml (e.g., ~/.dbt/profiles.yml)\n# Replace with your actual database details and environment variables\nprofiles_yml_content = f\"\"\"\nmy_oracle_project:\n  target: dev\n  outputs:\n    dev:\n      type: oracle\n      user: \"{os.environ.get('DBT_ORACLE_USER', 'your_user')}\"\n      password: \"{os.environ.get('DBT_ORACLE_PASSWORD', 'your_password')}\"\n      host: \"{os.environ.get('DBT_ORACLE_HOST', 'localhost')}\"\n      port: {os.environ.get('DBT_ORACLE_PORT', '1521')}\n      sid: \"{os.environ.get('DBT_ORACLE_SID', '')}\" # or service_name\n      service_name: \"{os.environ.get('DBT_ORACLE_SERVICE_NAME', 'your_service_name')}\"\n      schema: \"{os.environ.get('DBT_ORACLE_SCHEMA', 'your_schema')}\"\n      threads: 4\n      # Optional: tns_name, wallet_location, connect_string\n\"\"\"\n\n# Example of how you would set up your dbt project and run it via command line\n# This code snippet only shows the profile configuration setup conceptually.\n# Actual dbt operations are typically run from the terminal.\nprint(\"dbt-oracle profile configuration ready. Next, run dbt commands:\")\nprint(\"1. Initialize a dbt project: `dbt init <project_name>`\")\nprint(\"2. Test connection: `dbt debug`\")\nprint(\"3. Run transformations: `dbt run`\")\n","lang":"python","description":"To use dbt-oracle, you configure your Oracle connection details in a `profiles.yml` file, typically located in `~/.dbt/profiles.yml`. This configuration defines how dbt connects to your Oracle database. After setting up the profile, you can initialize a dbt project and run your models using standard dbt CLI commands like `dbt run`."},"warnings":[{"fix":"Always check the dbt-oracle GitHub releases or documentation for the `dbt-core` version it supports before upgrading either. For example, v1.9.4 requires `dbt-core` 1.10.","message":"dbt-oracle versions are tightly coupled with dbt-core versions. Upgrading dbt-core without ensuring compatibility with your dbt-oracle version will likely result in dependency conflicts or runtime errors.","severity":"breaking","affected_versions":"All versions"},{"fix":"Ensure your Python environment is version 3.9 or higher (current PyPI requires >=3.9).","message":"Support for Python 3.8 was dropped in version 1.8.4. Attempting to use dbt-oracle with Python 3.8 or older will fail.","severity":"breaking","affected_versions":"1.8.4 and later"},{"fix":"Refer to the `oracledb` documentation for its specific system requirements. Reinstall `oracledb` if you encounter issues after `dbt-oracle` upgrades its driver version.","message":"Frequent upgrades to the underlying `oracledb` Python driver can introduce new requirements or minor behavioral changes. Ensure your environment has the necessary Oracle Client libraries if using features like TNS or Wallets.","severity":"gotcha","affected_versions":"All versions (driver upgrades are common)"},{"fix":"Carefully review snapshot models and consider a full refresh or testing in a non-production environment after upgrading to these versions. Monitor for changes in hash collisions or validity period calculations.","message":"Snapshot behavior was significantly updated in v1.9.1 (stronger SHA-256 hash function) and v1.8.4 (`dbt_valid_to` column precision). Existing snapshots might behave differently or require regeneration after upgrading.","severity":"gotcha","affected_versions":"1.8.4, 1.9.1 and later"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Check `dbt-oracle`'s GitHub releases or documentation for compatible `dbt-core` versions. Reinstall `dbt-oracle` and `dbt-core` in a clean virtual environment, ensuring their versions align. Example: `pip install dbt-core==1.10.x dbt-oracle==1.9.4`.","cause":"The installed `dbt-oracle` version is not compatible with your `dbt-core` version, or `dbt-oracle` is not installed in the same environment as `dbt-core`.","error":"PackageNotFoundError: dbt-oracle is not installed for dbt-core==X.Y.Z"},{"fix":"Explicitly install the `oracledb` driver: `pip install oracledb`. If it's installed, ensure your `PATH` and `LD_LIBRARY_PATH` (or `DYLD_LIBRARY_PATH` on macOS) correctly point to your Oracle Client libraries if not using a thin client.","cause":"The `oracledb` Python driver, a required dependency for `dbt-oracle`, is not installed or not accessible in your Python environment.","error":"ModuleNotFoundError: No module named 'oracledb'"},{"fix":"Verify all connection details in your `profiles.yml` are accurate. Test connectivity using an external tool like SQL*Plus, SQL Developer, or `tnsping` with the same credentials. Ensure the Oracle database is accessible from the dbt machine.","cause":"The dbt profile's connection parameters are incorrect (user, password, host, port, SID/service_name, TNS alias), or there are underlying network/database authentication issues.","error":"ORA-XXXXX: connection error (e.g., ORA-12154, ORA-01017, ORA-28000)"},{"fix":"Upgrade your Python environment to version 3.9 or newer. Create a new virtual environment with a supported Python version and reinstall `dbt-oracle`.","cause":"You are trying to run `dbt-oracle` with an unsupported Python version (e.g., Python 3.8 or older).","error":"RuntimeError: Your Python version X.Y is not supported by dbt-oracle."}]}