dbt-altertable

A dbt adapter for Altertable, backed by Arrow Flight SQL.

Requirements

• Python 3.10+
• dbt-core >=1.8,<2.0

Installation

pip install dbt-altertable

Or with uv:

uv add dbt-altertable

Configuration

Add a profile to ~/.dbt/profiles.yml:

my_project:
  target: dev
  outputs:
    dev:
      type: altertable
      username: your_username
      password: your_password
      database: your_database
      schema: your_schema
      host: flight.altertable.ai # optional, this is the default
      port: 443 # optional, this is the default
      tls: true # optional, this is the default
      compute_size: XL # optional, server default if omitted

SQL dialect

dbt models should use DuckDB-compatible SQL. Altertable executes queries via DuckDB, so all DuckDB SQL features and functions are available — see the DuckDB SQL reference.

Compatibility with dbt-duckdb

The adapter builds on dbt-duckdb: duckdb__ macros from your project and packages (dbt_utils, dbt_date, ...) are used automatically.

Incremental strategies

Partitioning and sort order

Table and incremental models accept partitioned_by and sorted_by, applied when the table is created or fully refreshed:

{{ config(materialized='table', partitioned_by=['year(event_at)', 'country'], sorted_by=['event_at']) }}

Python models

Python table and incremental models run in the dbt process.

• dbt.ref() and dbt.source() load the whole relation into memory as a pyarrow.Table.
• Return anything pyarrow.table() accepts: pyarrow, pandas, polars or a DuckDB relation.
• Run SQL with session.cursor().execute(sql).table, which returns a pyarrow.Table.

Install packages in dbt's Python environment. Pandas indexes are not written: call reset_index() to keep a groupby key.

Unsupported on Altertable

These fail with an explicit error instead of silently producing a different model:

• indexes config
• Contract constraints other than not_null (primary_key, unique, foreign_key, check)
• grants config
• external and table_function materializations
• partitioned_by and sorted_by on Python models

Persisting model and column descriptions

When you enable persist_docs, dbt writes model and column description values to the warehouse using DuckDB’s COMMENT ON TABLE / COMMENT ON COLUMN syntax (one statement per column so Arrow Flight SQL accepts each round-trip).

Enable it in dbt_project.yml or on a model:

models:
  my_project:
    +persist_docs:
      relation: true
      columns: true

After a successful dbt run, descriptions show up on duckdb_tables() / duckdb_columns() (and therefore in dbt docs generate / catalog metadata).

Development

This project is managed with uv and hatchling.

git clone https://github.com/altertable-ai/dbt-altertable.git
cd dbt-altertable
uv sync --extra dev

Common tasks (see Makefile):

make lint        # ruff format + ruff check --fix
make typecheck   # ty check
make test        # pytest
make build       # uv build (wheel + sdist)

Integration tests

Flight SQL integration tests (for example persist_docs) run against altertable-mock in CI: the workflow builds the mock from main, starts it with --user dbt_ci:dbt_ci_secret, then runs pytest tests/integration. The default matrix job runs unit tests only (pytest --ignore=tests/integration).

Locally — Testcontainers (requires Docker; installs testcontainers via the integration extra):

ALTERTABLE_USE_TESTCONTAINERS=1 make test

make test detects that flag, runs uv sync --extra dev --extra integration, sets TESTCONTAINERS_RYUK_DISABLED=true by default (Ryuk often hangs on Docker Desktop), then runs the full pytest suite.

Or run only integration tests:

uv sync --extra dev --extra integration
export TESTCONTAINERS_RYUK_DISABLED=${TESTCONTAINERS_RYUK_DISABLED:-true}
ALTERTABLE_USE_TESTCONTAINERS=1 uv run pytest tests/integration -v

Optional overrides: ALTERTABLE_MOCK_IMAGE (default ghcr.io/altertable-ai/altertable-mock:latest), ALTERTABLE_MOCK_BOOT_USER (default dbt_ci:dbt_ci_secret, passed as --user to the mock), ALTERTABLE_MOCK_WAIT_TIMEOUT (seconds to wait for Starting Flight SQL server in logs, default 180).

If dbt run fails against the published image (for example catalog or information_schema errors), build the mock from source and point tests at it: docker build -t altertable-mock:local . then export ALTERTABLE_MOCK_IMAGE=altertable-mock:local — CI builds from main for the same reason.

Real Altertable — set the same ALTERTABLE_TEST_* variables to your Flight endpoint, catalog, and schema; do not set ALTERTABLE_USE_TESTCONTAINERS.

Optional pre-commit hooks:

uv run pre-commit install --hook-type pre-commit --hook-type commit-msg

Releases

Releases are managed via release-please — every push to main updates a rolling release PR. Merging it bumps the version, updates CHANGELOG.md, tags the release, and triggers PyPI publishing via trusted publishing.

Credits

This adapter draws on the design of dbt-duckdb.

License

MIT — see LICENSE.