dbt-opteryx

dbt adapter for Opteryx Cloud. It runs dbt Core 1.x against Opteryx's HTTP jobs API, using the DBAPI from opteryx-sqlalchemy.

Install

pip install dbt-opteryx

Profile

dbt's database is an Opteryx workspace and schema is a collection (workspace / collection are accepted as aliases). Every account has a personal space, personal.<your user>, which needs no setup:

my_project:
  target: cloud
  outputs:
    cloud:
      type: opteryx
      host: opteryx.app
      port: 443
      ssl: true
      user: "{{ env_var('OPTERYX_USER') }}"
      token: "{{ env_var('OPTERYX_TOKEN') }}"
      database: personal            # workspace
      schema: "{{ env_var('OPTERYX_USER') }}"  # collection
      threads: 1

Put this in dbt_project.yml (the leading-comment fix in opteryx-core has not been re-checked against opteryx.app):

query-comment:
  append: true

Behaviour to know about

• No transactions. Opteryx has none; every statement commits on its own. The adapter sends nothing for dbt's BEGIN/COMMIT.
• No temporary tables. dbt's __dbt_tmp intermediates are real tables, which dbt drops when the model succeeds. A failed model can leave one behind.
• Views are built with CREATE OR REPLACE VIEW, not dbt's rename swap.
• Seeds are inserted as typed literals (CAST('…' AS <type>)), not bind parameters.
• Incremental strategies: append, merge and delete+insert.
• Model contracts are refused, with an error naming the model: the adapter does not enforce them yet, and ignoring one silently would claim a guarantee it does not keep.
• Queries cannot be cancelled from dbt.
• Empty relations filter on WHERE 1 = 0. Opteryx refuses a bare literal as a WHERE clause, so the adapter replaces dbt's WHERE false in --empty refs and in the schema-only subquery dbt uses for unit tests and column introspection.
• Snapshots do not work. dbt's snapshot SQL selects *, <columns>, which Opteryx refuses (SELECT t.*, <columns> is accepted). See issue 14.

Integration tests

tests/integration/project is a dbt project covering seeds, sources (including freshness), view, table, ephemeral and incremental models (all three strategies), snapshots, hooks, contracts, generic, singular and unit tests, show, run-operation, --empty and docs generation. Run it against opteryx.app:

CLIENT_ID=… CLIENT_SECRET=… python tests/integration/run.py

Every step runs, and every node must pass except those listed in EXPECTED_FAILURES in run.py, which must fail. The run fails on an unexpected failure and also on an expected failure that passes, so the list is pruned as Opteryx gaps close.

It writes into personal.$CLIENT_ID (override with OPTERYX_WORKSPACE / OPTERYX_COLLECTION). CI runs it on push (.github/workflows/integration.yaml), reading CLIENT_ID / CLIENT_SECRET from the OPTERYX_TEST_CLIENT / OPTERYX_TEST_TOKEN repository secrets. That is a service account, which has no personal space, so CI writes into opteryx_ci.dbt.

Offline checks (no connection) run with python -m pytest tests/unit.

CI

Repository secrets: OPTERYX_TEST_CLIENT, OPTERYX_TEST_TOKEN (integration), UPLOAD_CLIENT, UPLOAD_TOKEN (Semgrep upload).

Releasing

Bump version in dbt/adapters/opteryx/__version__.py (the package version is read from it), then push a matching vX.Y.Z tag. PyPI must list this repository's release.yaml as a trusted publisher for dbt-opteryx; for the first release that is a pending publisher, set up on PyPI before the tag is pushed.

Verification against opteryx.app (2026-11-09, re-run 2026-11-13)

dbt-core 1.12.6, dbt-adapters 1.24.5, opteryx-sqlalchemy 0.0.13.

Issues found