Установка dbt-core + dbt-duckdb

Этот урок проведёт вас от «нет dbt на машине» до «работающий dbt-core 1.10 с DuckDB-адаптером». На всё уйдёт 5-10 минут.

Предусловия

Перед установкой убедитесь, что у вас есть:

1. Python 3.10 или выше (3.11 / 3.12 — оптимально). dbt-core 1.10 требует Python не меньше 3.10.
2. pip (поставляется с Python)
3. Терминал: bash / zsh / PowerShell — что угодно

Проверьте версию Python:

python3 --version

Ожидаемый вывод (любая версия 3.10+):

Python 3.12.4

Если python3 не найден или версия слишком старая — установите подходящую через:

• macOS: brew install [email protected]
• Linux (Ubuntu/Debian): sudo apt install python3.12 python3.12-venv
• Windows: загрузите с python.org или через winget install Python.Python.3.12

Virtual environment: зачем и как

Virtual environment (venv) — это изолированное пространство для Python-пакетов проекта. Без venv pip install ставит пакеты глобально, и через год у вас будет 200 несовместимых версий пакетов от разных проектов в одной системе.

Создаём папку для проекта и venv внутри:

mkdir ~/dbt-projects && cd ~/dbt-projects
python3 -m venv .venv

Что произошло:

• В ~/dbt-projects/.venv/ создалась изолированная Python-среда
• Внутри есть свой bin/python, свой bin/pip, свои site-packages

Активируем venv:

# macOS / Linux:
source .venv/bin/activate

# Windows (PowerShell):
.venv\Scripts\Activate.ps1

После активации в терминале появится префикс (.venv):

(.venv) lev@macbook ~/dbt-projects $

С этого момента все pip install и python будут работать только в venv, не трогая системный Python.

Установка dbt-core + dbt-duckdb

В активированном venv:

pip install --upgrade pip
pip install dbt-core dbt-duckdb

Что произойдёт:

1. pip тянет dbt-core (последний релиз) из PyPI
2. Затем dbt-duckdb (адаптер для DuckDB)
3. Адаптер сам тянет нужную версию DuckDB как Python-пакет

Зависимости автоматически:

• dbt-core — само ядро
• dbt-common, dbt-adapters — общие библиотеки
• dbt-semantic-interfaces — для metrics / Semantic Layer
• duckdb — Python-пакет с встроенной DuckDB
• Jinja2, agate, click, mashumaro, protobuf — runtime-зависимости

На моём ноутбуке (MacBook Pro M2) установка занимает ~30 секунд. Размер .venv/ после установки — ~150 MB.

Version pinning: критически важно

Команда pip install dbt-core dbt-duckdb тянет последние версии. На long-term проектах это плохо: завтра выйдет dbt-core 1.11, и pip install поставит её, ломая ваш проект тестами на 1.10.

Best practice — фиксировать версии:

pip install dbt-core==1.10.* dbt-duckdb==1.10.*

Звёздочка позволяет patch-обновления (1.10.0 -> 1.10.5), но не пускает minor-апгрейд (1.11.x).

Ещё лучше — записать установленные версии в файл:

pip freeze > requirements.txt

Внутри requirements.txt будут полные версии:

dbt-adapters==1.10.4
dbt-common==1.20.1
dbt-core==1.10.3
dbt-duckdb==1.10.1
dbt-semantic-interfaces==0.8.5
duckdb==1.1.3
Jinja2==3.1.4
mashumaro==3.13.1
...

Теперь любой коллега через pip install -r requirements.txt получит точно такой же набор пакетов.

Проверка установки: dbt —version

После установки запустите:

dbt --version

Ожидаемый вывод:

Core:
  - installed: 1.10.3
  - latest:    1.10.3 - Up to date!

Plugins:
  - duckdb:    1.10.1 - Up to date!

Что здесь:

• Core — версия dbt-core
• Plugins — все установленные adapters (у нас один — duckdb)
• Up to date — pip mirror сравнил с последней PyPI-версией

Если получаете command not found: dbt — значит venv не активирован, или вы поставили dbt в другую среду. Проверьте через which dbt (macOS/Linux) или where dbt (Windows): путь должен начинаться с .venv/bin/dbt.

dbt —help: что есть в CLI

Другая первая команда после установки:

dbt --help

Сокращённый вывод (релевантные команды):

Usage: dbt [OPTIONS] COMMAND [ARGS]...

  An ELT tool for managing your SQL transformations and data models.
  For more documentation on these commands, visit: docs.getdbt.com

Commands:
  build           Run all seeds, models, snapshots, and tests in DAG order.
  clean           Delete target/ and dbt_packages/
  clone           Create clones of selected nodes
  compile         Generate executable SQL from source, model, test, and analysis files.
  debug           Show information on the current dbt environment and a connection test.
  deps            Update the dbt packages from packages.yml.
  docs            Generate or serve the documentation website
  init            Initialize a new dbt project.
  list            List the resources in your project
  parse           Parses the project and provides information on performance.
  retry           Retry the nodes that failed in the previous run.
  run             Compile SQL and execute against the current target database.
  run-operation   Run the named macro with any supplied arguments.
  seed            Load data from csv files into your warehouse.
  show            Generates executable SQL for a named resource or inline query.
  snapshot        Execute snapshots defined in your project.
  source          Manage your project's sources
  test            Runs tests on data in deployed models.

Основные команды, с которыми будете работать:

Альтернативные способы установки

Знать на случай, если столкнётесь:

1. uv (рекомендуется для скорости):

pip install uv
uv venv && source .venv/bin/activate
uv pip install dbt-core dbt-duckdb

2. pipx (для CLI tools):

pipx install dbt-core
pipx inject dbt-core dbt-duckdb

pipx создаёт venv под каждый CLI-инструмент автоматически. Но для dbt-проектов это менее удобно: на разных проектах могут быть разные adapter’ы.

3. Conda:

conda create -n dbt python=3.12
conda activate dbt
pip install dbt-core dbt-duckdb

Conda иногда используется в data science командах. Для dbt это не даёт преимуществ перед venv + pip.

4. Docker:

dbt Labs публикует Docker images: ghcr.io/dbt-labs/dbt-core. Но для локальной разработки venv быстрее и удобнее. Docker имеет смысл в CI / production runners.

5. dbt Cloud (без локальной установки):

Если используете dbt Cloud — локально dbt можно не ставить, IDE доступен в браузере. Но для DuckDB это не вариант (Cloud не поддерживает DuckDB).

Что делать, если установка падает

Топ-3 типичные проблемы:

1. ModuleNotFoundError: No module named 'dbt' после установки

-> Venv не активирован. Проверьте префикс (.venv) в терминале. Если нет — source .venv/bin/activate.

2. ERROR: Could not build wheels for psycopg2-binary (на macOS / Linux)

-> Не относится к dbt-duckdb напрямую (это для dbt-postgres). Если ставите dbt-duckdb — psycopg не нужен. Если случайно установили dbt-postgres — переустановите только dbt-core и dbt-duckdb.

3. dbt —version показывает несовместимые версии (Core 1.10, duckdb 1.7)

-> Адаптер устарел. Обновите: pip install --upgrade dbt-duckdb. dbt-duckdb 1.10.x совместим с dbt-core 1.8-1.10.

Для не-английских ошибок — приветствуется поиск в Troubleshooting курса и в Telegram-группе.

Когда обновляться

Стратегия для junior-проекта:

1. Patch updates (1.10.0 -> 1.10.5): автоматически через pip install --upgrade dbt-core==1.10.*. Безопасно — patch только баг-фиксы.
2. Minor updates (1.10 -> 1.11): читать release notes! Внимание на deprecations и breaking changes. Делать на отдельной ветке, прогонять dbt test. Обычно 1-2 раза в год.
3. Major (1.x -> 2.x): dbt-core 2.0 не вышел; когда выйдет, ждите 3-6 месяцев на стабилизацию.

Для DuckDB-адаптера примерно то же. Обращайте внимание на совместимость: dbt-duckdb 1.10.x ↔ dbt-core 1.8-1.10.

Попробуй сам

Прямо сейчас:

1. Создайте папку ~/dbt-projects/ (или где удобно)
2. Создайте venv: python3 -m venv .venv
3. Активируйте: source .venv/bin/activate
4. Установите: pip install dbt-core dbt-duckdb
5. Проверьте: dbt --version — должно показать Core 1.10.x и Plugin duckdb 1.10.x
6. Запустите: dbt --help — посмотрите список команд

Если все 6 шагов прошли успешно — вы готовы к следующему уроку, где мы создадим первый проект через dbt init.