Гибридная разработка с dbt platform и dbt v2
Введение
Гибридные развертывания dbt становятся всё более распространенными. Пользователи dbt v2 часто работают сразу в нескольких местах: в dbt platform для выполнения запусков в рабочей среде и разработки в IDE, а также на локальном компьютере с помощью CLI dbt platform или расширения dbt для VS Code.
Эти варианты работы полностью поддерживаются для пользователей dbt platform. Согласование учетных данных, переменных окружения и версий движка между средами — одна из первых эксплуатационных задач, с которыми сталкиваются команды.
В этом руководстве рассматриваются выбор команды для запуска нужного инструмента, учетные данные, переменные окружения, версии dbt v2, а также Mesh и отложенное разрешение ссылок (deferral). Для поддержания согласованности приведены конкретные шаги с примерами, готовыми к копированию.
Если в одном проекте вы используете и dbt platform CLI, и локальную сборку dbt v2, начните с раздела Выбор запускаемой программы dbt. Оба инструмента вызываются командой dbt, и далее в руководстве предполагается, что вы умеете их различать.
Предварительные требования
- У вас есть учетная запись dbt platform как минимум с одним проектом, использующим dbt v2.
- У вас установлен либо dbt platform CLI, либо расширение dbt для VS Code и локальная версия dbt.
Выбор запускаемой программы dbt
Если вы установите и dbt platform CLI, и локальную сборку dbt v2, на вашем компьютере окажутся две отдельные программы, которые вызываются одной и той же командой dbt. Прежде чем настраивать учетные данные, переменные окружения или версии, убедитесь, что вы однозначно определили, какую из них вызываете.
Пропустите этот раздел, если вы устанавливаете только один из этих двух инструментов.
Два варианта выполнения
И dbt platform CLI, и локальная версия dbt v2 читают одни и те же файлы проекта — один клон репозитория, один dbt_project.yml, один набор моделей, макросов и тестов. Различаются место выполнения работы и источник сведений о подключении.
| Аспект | dbt platform CLI | Локальная версия dbt v2 |
|---|---|---|
| Что это | Клиент, который отправляет вашу команду в dbt platform | Исполняемый файл dbt, который запускается на вашем компьютере |
| Где выполняется dbt | В инфраструктуре dbt platform | Локально или внутри виртуальной машины вашего агента |
Назначьте каждому инструменту отдельную команду
Поскольку обе программы устанавливаются под именем dbt, при вызове dbt запускается та, которая первой найдется в $PATH. Чтобы не зависеть от порядка записей в $PATH, можно назначить хотя бы одной из них псевдоним, который позволит явно вызывать нужную программу из командной строки.
Скрипт установки dbt v2 уже создает псевдоним dbtf, указывающий на локальный бинарный, или исполняемый, файл dbt v2. Вы также можете добавить псевдоним dbt-cli для dbt platform CLI, чтобы каждая команда вызывала именно тот инструмент, который обозначен ее именем, например:
dbtf build --select my_model # Runs locally, on your installed v2 binary
dbt-cli build --select my_model # Runs on dbt platform, on your environment's release track
Чтобы настроить псевдоним, выполните следующие действия:
-
Выясните, какая программа сейчас вызывается командой
dbtи установлено ли несколько таких программ:which -a dbt -
Установите необходимые инструменты:
- Установите dbt v2 с помощью скрипта установки, который размещает его в
$HOME/.local/bin/dbtна macOS и Linux или вC:\Users\USERNAME\.local\bin\dbt.exeна Windows и добавляет псевдонимdbtf. - Отдельно установите dbt platform CLI.
- Установите dbt v2 с помощью скрипта установки, который размещает его в
-
Используя путь к установленному dbt platform CLI, определенный на шаге 1, добавьте в файл профиля оболочки псевдоним, указывающий на его исполняемый файл.
Например, на macOS при установке через Homebrew можно создать псевдоним для исполняемого файла
/opt/homebrew/bin/dbt:# ~/.zshrc or ~/.bashrc
alias dbt-cli="/opt/homebrew/bin/dbt"Перезагрузите профиль оболочки:
source ~/.zshrc # or source ~/.bashrc -
Убедитесь, что каждая команда вызывает ожидаемый инструмент, а строки версий у них различаются:
dbtf --version
dbt-cli --version -
Определите, какая программа должна запускаться при вызове просто
dbtна вашем компьютере, и установите соответствующее правило для команды. При любом выбореdbtfиdbt-cliбудут однозначно запускать обозначенные ими программы.
dbtf и dbt-cli — это псевдонимы оболочки. Они доступны в интерактивном терминале, но не в рецептах Makefile, скриптах оболочки, заданиях CI или командах, которые ИИ-агент выполняет в неинтерактивной оболочке. В этих случаях используйте абсолютный путь к исполняемому файлу или задайте порядок записей в $PATH так, чтобы команда dbt вызывала нужный инструмент.
Команды, которые имеют разное значение в каждом инструменте
Большинство команд (build, run, test, compile) работают одинаково, но выполняются в разных местах. Некоторые команды предназначены только для одного инструмента, и их вызов в другом либо завершается ошибкой, либо приводит к неожиданному результату:
dbt system updateиdbt system uninstallуправляют локальной установкой dbt v2. Они неприменимы к dbt platform CLI и не влияют на dbt platform.dbt initзаполняет локальный файлprofiles.yml. Он нужен для работы с локальной версией dbt v2, но не для dbt platform CLI, который не используетprofiles.yml.dbt debugпроверяет локальный профиль, целевую конфигурацию и подключение. Для получения сведений о среде и подключении dbt platform CLI используйтеdbt environment.
Если установлены оба инструмента, записывайте эти команды как dbtf system update, dbtf init и dbtf debug, чтобы исключить неоднозначность.
Как редакторы и агенты выбирают dbt
Каждый инструмент в вашем рабочем процессе определяет вызываемый dbt по собственным правилам. Настройка одного инструмента не настраивает остальные.
| Где вы запускаете dbt | Как выбирается dbt | Что нужно настроить |
|---|---|---|
| Расширение dbt для VS Code | Параметр dbt.fusionPath или сборка v2, которую расширение загружает и обслуживает самостоятельно | Не задавайте dbt.fusionPath, чтобы расширение само управляло v2. Если вы устанавливаете v2 самостоятельно, укажите абсолютный путь к исполняемому файлу v2 |
| Встроенный терминал VS Code или Cursor | Переменная $PATH оболочки и псевдонимы из ее профиля | Псевдонимы dbtf и dbt-cli, описанные выше |
| Агенты для программирования, например Claude Code или агентный режим Cursor | Неинтерактивная оболочка — $PATH действует, а псевдонимы оболочки обычно нет | Абсолютные пути к исполняемым файлам и явно записанное правило выбора команд в файле инструкций агента |
| Удаленные виртуальные машины агентов | Собственная переменная $PATH виртуальной машины, а не вашей рабочей станции | Установите оба инструмента в виртуальной машине, закрепите их установку в конфигурации настройки, чтобы они сохранялись в новых сеансах, и храните учетные данные в менеджере секретов этой платформы |
dbt.fusionPath — не настройка терминалаdbt.fusionPath указывает расширению dbt для VS Code, какой исполняемый файл использовать для запуска LSP и собственных действий меню расширения. Этот параметр не влияет ни на команды, которые вы вводите во встроенном терминале, ни на команды, выполняемые агентом. Он должен указывать на корректный исполняемый файл dbt v2 — это должен быть абсолютный путь в файловой системе, а не имя псевдонима и не dbt platform CLI.
Чтобы найти путь для этого параметра, выполните:
command -v dbtf
Храните абсолютные пути, зависящие от конкретного компьютера, в пользовательских настройках, а не в настройках рабочей области, добавляемых в репозиторий. Так настройка не нарушит работу коллег, у которых пути отличаются.
Укажите агенту для программирования, какую команду использовать
Агенты выполняют команды оболочки так же, как скрипты: они наследуют $PATH, но не ваши интерактивные псевдонимы, и не могут догадаться, какой вариант выполнения вы имели в виду. Зафиксируйте соглашение в файле инструкций, который читает агент: CLAUDE.md, AGENTS.md, .cursor/rules/ или аналогичном файле для вашего инструмента:
## dbt command routing
Replace the paths below with the output of `which -a dbt` on this machine.
- Use `$HOME/.local/bin/dbt` for local dbt v2 commands. It runs on this machine
against `profiles.yml`.
- Use `/opt/homebrew/bin/dbt` for dbt platform CLI commands. It runs on
dbt platform against the environment's release track.
- Never substitute one for the other.
- Run dbt commands from the repository root.
- Ask before running any command that creates or modifies warehouse objects.
В инструкциях агента используйте абсолютные пути вместо псевдонимов dbtf и dbt-cli, поскольку оболочка агента может не загружать ваш профиль оболочки. Определите фактические пути на компьютере, где работает агент, с помощью which -a dbt и обновляйте файл инструкций при их изменении. На удаленной виртуальной машине агента проверяйте пути в новом сеансе: инструменты, установленные вручную в предыдущем сеансе, могут не сохраниться.
Управление учетными данными
Способ локальной аутентификации в хранилище данных зависит от того, какой самостоятельно размещенный инструмент вы используете:
- dbt platform CLI: для разработки только через CLI (без расширения dbt для VS Code) используйте dbt platform CLI, выбрав dbt v2 в качестве канала релизов платформы. Учетные данные хранилища централизованно управляются в dbt platform и передаются автоматически — файл
profiles.ymlне требуется. - Расширение dbt для VS Code: для локальной разработки в IDE расширение dbt для VS Code запускает dbt v2 и его функции LSP в локальном процессе. Для этого варианта требуется файл
profiles.yml, обеспечивающий прямое подключение к хранилищу данных.
dbt platform CLI
dbt platform CLI — самый простой вариант для пользователей dbt platform, которым нужен локально установленный CLI без VS Code. Он выполняет аутентификацию через ваш сеанс dbt platform, а учетные данные хранилища централизованно управляются в dbt platform и передаются автоматически.
Подробные инструкции по установке см. в разделе Установка dbt platform CLI. dbt platform CLI устанавливается из локальной командной строки.
Файл конфигурации, скачанный из раздела Account settings в dbt platform, обеспечит подключение и аутентификацию с использованием существующих учетных данных.
Это самый простой вариант для команд, которым не нужна полноценная локальная интеграция с IDE.
Расширение dbt для VS Code (требуется profiles.yml)
Расширение dbt для VS Code запускает dbt v2 и его языковой сервер в локальном процессе и подключается непосредственно к вашему хранилищу данных. Поэтому для локальных сеансов разработки с расширением нужен файл profiles.yml.
Скачайте dbt_cloud.yml из раздела Account settings в dbt platform, и dbt v2 попытается автоматически заполнить неконфиденциальные метаданные учетных данных из dbt platform.
Если вы получили доступ к новому проекту, повторно скачайте файл dbt_cloud.yml, прежде чем работать с ним локально. Чтобы переключаться между проектами, уже перечисленными в файле, обновите context.active-project. Чтобы не воссоздавать конфигурацию хранилища вручную, используйте dbt init.
dbt init
dbt v2 загружает такие поля, как имя пользователя, роль, вычислительное хранилище (warehouse), база данных и схема, но никогда не загружает конфиденциальные значения, такие как пароли или токены. Если ваш механизм аутентификации не требует пароля (например, externalbrowser или OAuth на основе SSO), dbt v2 настроит и его, чтобы вы могли работать без локального хранения секретов.
Такое заполнение выполняется один раз при первоначальной настройке и не синхронизируется автоматически. Если конфигурация хранилища в dbt platform изменится, снова выполните dbt init, чтобы обновить локальный profiles.yml.
Мастер первоначальной настройки расширения dbt для VS Code проводит вас через этот процесс, поэтому обычно запускать dbt init вручную не нужно.
Мы работаем над решением, которое позволит разрабатывать локально в расширении dbt для VS Code, полностью управляя учетными данными в dbt platform, без локального profiles.yml. Мы обновим эту страницу, когда решение станет доступно.
Управление переменными окружения
Переменные окружения, заданные в dbt platform, применяются к запускам в рабочей среде и сеансам Studio IDE. Для локальной разработки переменными окружения нужно управлять отдельно.
dbt platform CLI
При использовании dbt platform CLI платформа dbt platform добавляет в ваш сеанс dbt platform CLI те же переменные окружения, которые используются в рабочей среде. Дополнительная настройка не требуется.
Расширение VS Code (файл .env)
Расширение dbt для VS Code запускает dbt v2 как локальный процесс, поэтому переменные окружения из dbt platform недоступны автоматически. Вместо этого используйте файл .env в корне проекта dbt:
# .env
DBT_MY_DATABASE=my_database
DBT_MY_SCHEMA=my_dev_schema
DBT_TARGET_SCHEMA=analytics_dev
dbt v2 и расширение dbt для VS Code автоматически загружают значения из этого файла. Вы также можете просматривать и переопределять отдельные переменные окружения в интерфейсе настроек расширения.
Ссылайтесь на эти переменные в profiles.yml или в других частях проекта dbt с помощью функции Jinja env_var:
# profiles.yml
my_profile:
target: dev
outputs:
dev:
type: snowflake
account: my_account
database: "{{ env_var('DBT_MY_DATABASE') }}"
schema: "{{ env_var('DBT_MY_SCHEMA') }}"
Подробное описание использования файла .env, приоритетов переменных и расположения настроенных переменных см. в разделе Переменные окружения, а инструкции по локальной настройке — в разделе Локальная настройка переменных окружения.
Согласование переменных платформы и локальных переменных
Переменные окружения в dbt platform и локальном файле .env не синхронизируются автоматически.
Добавьте в репозиторий файл .env.example со списком обязательных переменных. Каждый разработчик копирует его локально и заполняет собственными значениями; эта копия никогда не добавляется в репозиторий.
# .env.example (committed to version control)
DBT_MY_DATABASE= # Your development database name
DBT_MY_SCHEMA= # Your personal dev schema, for example dbt_yourname
DBT_TARGET_SCHEMA= # Target schema for dbt output
# Developer setup: copy the example and fill in your values
cp .env.example .env
dbt v2 и расширение dbt для VS Code загружают переменные только из файла с точным именем .env, поэтому каждому разработчику нужна собственная копия. Убедитесь, что .env указан в .gitignore, чтобы учетные данные никогда не попадали в репозиторий. Команда dbt init добавляет эту запись автоматически.
echo ".env" >> .gitignore
Когда переменные окружения в dbt platform меняются (вы добавляете переменные или переименовываете значения), обновляйте .env.example в том же pull request, чтобы локальные разработчики знали, что нужно обновить собственный .env.
Рассмотрите возможность использования скрипта, который в начале сеанса получает переменные из менеджера секретов (например, AWS Secrets Manager или 1Password) и записывает их в .env, вместо долговременного хранения значений в файле.
Управление версиями dbt v2
Канал релизов v2 Stable в dbt platform постоянно обновляется по мере выхода новых релизов dbt v2. Если локальная версия отстает, поведение может различаться. Один и тот же запрос может компилироваться локально иначе, чем в рабочей среде, а какая-либо функция может быть доступна в dbt platform, но отсутствовать в локальном исполняемом файле. Поддерживайте актуальную версию, чтобы избежать таких расхождений.
Перевод среды dbt platform на канал релизов v2 изменяет движок, который dbt platform использует для этой среды. Он не устанавливает, не обновляет, не заменяет и не выбирает исполняемый файл dbt v2 на вашем компьютере и не превращает dbt platform CLI в dbt v2.
Обратное тоже верно: локальный запуск dbt system update обновляет только вашу локальную установку. Он не влияет на то, какую сборку используют ваши среды dbt platform.
Рассматривайте эти две настройки версии как независимые и самостоятельно поддерживайте их согласованность с помощью шагов из этого раздела.
Версии на dbt platform
В dbt platform движок dbt v2 использует модель каналов релизов без привязки к конкретной версии. Канал релизов по умолчанию — v2 Stable; он всегда использует последний стабильный релиз. Подробности о каналах релизов и уровнях их стабильности см. в разделе Релизы dbt v2.
Версии, установленные локально
По умолчанию инструкции по установке dbt v2 устанавливают последний стабильный релиз — ту же версию, которая поставляется в канале релизов v2 Stable на dbt platform:
# macOS / Linux
pip install dbt
Чтобы в любой момент обновить самостоятельно размещенную установку до последнего стабильного релиза:
dbt system update
Чтобы проверить текущую версию:
dbt --version
Согласование версий: контейнеры разработки (рекомендуется)
Для наиболее надежного соответствия локальных версий dbt v2 и dbt platform используйте контейнер разработки VS Code. Контейнер разработки запускает вашу среду внутри образа Docker, который пересобирается в начале каждого сеанса и каждый раз заново устанавливает dbt v2. Так все участники команды используют ту же версию, что и dbt platform, без ручных обновлений.
Наши коллеги из Brooklyn Data опубликовали готовый контейнер разработки для dbt v2:
- Шаблон контейнера разработки: brooklyn-data/dbt-fusion-devcontainer
- Статья в блоге: Почему стоит использовать контейнеры разработки с dbt v2
Чтобы начать работу с их шаблоном:
# Clone the devcontainer template into your project
curl -fsSL https://raw.githubusercontent.com/brooklyn-data/dbt-fusion-devcontainer/main/setup.sh | sh
Затем откройте проект в VS Code и при появлении запроса выберите Reopen in Container. VS Code автоматически соберет образ и установит последний стабильный релиз dbt v2.
Мы добавляем в dbt platform новые каналы релизов dbt v2 помимо v2 Stable. Когда они станут доступны, мы дополним это руководство инструкциями по привязке контейнера разработки к определенному каналу.
Без контейнеров разработки: обновление в начале каждого сеанса
Если ваша команда не может использовать контейнеры разработки, вместо этого запускайте dbt system update в начале каждого сеанса разработки. Эта команда устанавливает последний стабильный релиз — ту же версию, что и в канале v2 Stable на dbt platform, — поэтому локальный исполняемый файл остается актуальным:
dbt system update && dbt debug
Фиксация конкретного номера версии здесь не подходит для долгосрочного использования: канал v2 Stable в dbt platform продолжает обновляться, и самостоятельно размещенная установка с закрепленной версией отстает. Старайтесь оставаться на v2 Stable, а не привязываться к одному релизу.
Чтобы об этом было проще помнить, добавьте цель dev в Makefile проекта:
# Makefile
.PHONY: dev
dev:
dbt system update
dbt debug
Тогда разработчики будут начинать сеанс с команды:
make dev
Вы также можете описать это соглашение в CONTRIBUTING.md проекта, чтобы оно стало частью контрольного списка для новых участников.
dbt Mesh и отложенное разрешение ссылок
Если ваш проект использует dbt Mesh, ссылаясь на модели из других проектов dbt через межпроектные ссылки, dbt v2 обрабатывает их автоматически во время разработки при наличии dbt_cloud.yml.
Как это работает
Когда dbt v2 обнаруживает вышестоящие проекты, определенные в dependencies.yml, он скачивает артефакт публикации каждого такого проекта из dbt platform перед разрешением межпроектных ссылок. После этого ref('upstream_project', 'model_name') работает локально без ручной настройки.
При разрешении межпроектных ссылок dbt v2 добавляет в журналы строки, подобные следующим:
Downloading publication artifact for <upstream_project> (resolving cross-project refs)
Downloaded publication artifact for <upstream_project> to <path> (resolving cross-project refs)
dbt v2 кеширует скачанные артефакты публикации на срок до одного часа, поэтому последующие запуски в том же сеансе пропускают скачивание и разрешают ссылки из локального кеша.
Автоматическое отложенное разрешение ссылок также включено по умолчанию. При наличии dbt_cloud.yml движок dbt v2 использует настроенную для проекта среду отложенного разрешения ссылок: вы собираете только измененные модели и зависящие от них нижестоящие модели, а остальные ссылки разрешаются по состоянию рабочей среды.
Отключение отложенного разрешения ссылок
-
В расширении VS Code: отключите автоматическое отложенное разрешение ссылок в настройках расширения. Найдите
Dbt > Flag: Deferи снимите флажок:
Настройки отложенного разрешения ссылок в расширении dbt для VS Code -
В CLI: передайте
--no-deferлюбой команде, чтобы пропустить и отложенное разрешение ссылок, и скачивание артефакта публикации:dbt run --no-defer
dbt compile --no-defer
Справочная таблица
В следующей таблице приведены основные различия между двумя вариантами разработки, рассмотренными в этом руководстве:
| Аспект | dbt platform CLI | Расширение dbt для VS Code |
|---|---|---|
| Команда, когда установлены оба инструмента | dbt-cli (псевдоним, который добавляете вы) | dbtf (псевдоним, который добавляет установщик) |
| Учетные данные | Управляются через ваш сеанс dbt platform, файл profiles.yml не требуется | Требуется profiles.yml; используйте dbt init для заполнения данными из dbt platform |
| Переменные окружения | Автоматически используются те же переменные окружения, что и в dbt platform | Используйте файл .env в корне проекта |
| Управление версиями | dbt system update для поддержания актуальной версии | Для автоматической синхронизации рекомендуется контейнер разработки |
| dbt Mesh / отложенное разрешение ссылок | Включается автоматически при наличии dbt_cloud.yml; для отключения используйте --no-defer | Включается автоматически при наличии dbt_cloud.yml; отключается в настройках расширения |