Перейти к основному содержимому

Установка расширения dbt для VS Code Preview

Расширение dbt — доступно для VS Code, Cursor и Windsurf — использует dbt Fusion Engine, чтобы сделать разработку в dbt более удобной и эффективной.

примечание

Это единственное официальное расширение dbt Labs для VS Code. Другие расширения могут работать вместе с расширением dbt для VS Code, но они не тестируются и не поддерживаются dbt Labs. Актуальные обновления читайте в Fusion Diaries.

Предварительные требования​

Перед установкой обязательно ознакомьтесь со страницей Limitations, так как некоторые функции пока не поддерживают Fusion.

Для использования расширения необходимо выполнить следующие требования:

PrerequisiteDetails
dbt Fusion EngineРасширение dbt для VS Code требует наличия бинарного файла dbt Fusion Engine (небольшой исполняемый файл). Расширение предложит установить его автоматически, либо вы можете установить его вручную в любое время.

Зарегистрируйте email в течение 14 дней после установки расширения dbt. Бесплатно для команд до 15 пользователей.
Project files- Вам необходим файл конфигурации profiles.yml.

⁃ В зависимости от выбранного пути регистрации, вам может понадобиться загрузить файл dbt_cloud.yml.

⁃ Для использования расширения проект dbt platform не требуется.
EditorРедактор кода VS Code, Cursor или Windsurf.
Operating systemsКомпьютер под управлением macOS, Windows или Linux.
Configure your local setup (Optional)Настройте расширение, чтобы локально воспроизвести вашу среду dbt, а также задайте локальные переменные окружения для использования возможностей расширения VS Code.
Run dbt-autofix (Optional)Запустите dbt-autofix, чтобы исправить ошибки и устаревшие элементы в вашем проекте dbt.
Loading table...

Установите расширение​

Чтобы установить расширение dbt для VS Code, выполните следующие шаги в выбранном редакторе:

  1. Перейдите на вкладку Extensions и найдите dbt. Выберите расширение от издателя dbtLabsInc или dbt Labs Inc и нажмите Install.
    Поиск расширенияПоиск расширения
  2. Откройте dbt‑проект в среде VS Code, если вы ещё этого не сделали, и убедитесь, что он добавлен в текущее рабочее пространство. Если в строке состояния редактора отображается метка dbt Extension, значит расширение успешно установлено. Наведите курсор на эту метку, чтобы увидеть диагностическую информацию.
    Если вы видите метку 'dbt Extension`, расширение активированоЕсли вы видите метку 'dbt Extension`, расширение активировано
  3. После активации расширение автоматически начнёт загрузку подходящего dbt Language Server (LSP) для вашей операционной системы.
    Языковой сервер dbt будет установлен автоматическиЯзыковой сервер dbt будет установлен автоматически
  4. Если dbt Fusion engine ещё не установлен на вашем компьютере, расширение предложит скачать и установить его. Следуйте инструкциям в уведомлении или установите его вручную из командной строки.
    Следуйте подсказке, чтобы установить движок dbt FusionСледуйте подсказке, чтобы установить движок dbt Fusion
  5. Запустите инструмент обновления расширения VS Code, чтобы подготовить ваш dbt‑проект к работе с Fusion и исправить ошибки и устаревшие конструкции.
  6. (Необязательно) Если вы впервые используете расширение или VS Code/Cursor, вы можете настроить локальную среду, чтобы она соответствовала вашей среде dbt platform, и задать локальные переменные окружения для использования функций расширения.

Расширение dbt установлено и готово к работе! Дальнейшие шаги:

  • Перейдите к разделу getting started, чтобы начать процесс онбординга через терминал и настроить окружение. Если вы столкнётесь с ошибками парсинга, можно также запустить инструмент dbt-autofix.

  •  Установите dbt Fusion engine из командной строки, если вы ещё этого не сделали.

    Если у вас уже установлен dbt Fusion Engine, вы можете пропустить этот шаг. Если он у вас не установлен, выполните следующие действия для установки:

    1. Откройте новое окно командной строки и выполните следующую команду, чтобы установить dbt Fusion Engine:

      Выполните следующую команду в терминале:

      curl -fsSL https://public.cdn.getdbt.com/fs/install/install.sh | sh -s -- --update

      Чтобы начать использовать dbtf сразу после установки, перезагрузите вашу оболочку, чтобы новая переменная $PATH была распознана:

      exec $SHELL

      Либо закройте и снова откройте окно терминала. Это загрузит обновлённые настройки окружения в новую сессию.

    2. Выполните следующую команду, чтобы убедиться, что вы установили Fusion:

      dbtf --version

      Вы можете использовать dbt или его алиас Fusion — dbtf (это удобно, если у вас уже установлен другой CLI dbt). Путь установки по умолчанию:

      • macOS/Linux: $HOME/.local/bin/dbt
      • Windows: C:\Users\<username>\.local\bin\dbt.exe

      Установщик добавляет этот путь автоматически, но вам может потребоваться перезагрузить оболочку, чтобы команда dbtf стала доступной.

    1. Следуйте руководству getting started, чтобы начать работу с расширением. Вы можете выбрать один из способов:
      • Запустить dbtf init для терминального онбординга.
      • Выполнить команду Run dbt: Register dbt extension через command palette.
      • Использовать кнопку Get started в меню расширения.

  • Зарегистрируйте расширение с помощью email или учётной записи dbt platform, чтобы продолжить использование после пробного периода.

  • Ознакомьтесь с ограничениями и неподдерживаемыми возможностями, если вы ещё этого не сделали.

Начало работы​

После установки dbt Fusion Engine и расширения dbt для VS Code на боковой панели появится логотип dbt. Отсюда вы можете запускать рабочие процессы для начала работы, просматривать информацию о расширении и вашем dbt‑проекте, а также использовать полезные ссылки. Подробнее см. документацию о меню расширения dbt.

Начать работу с расширением можно несколькими способами:

  • Запустить dbtf init для онбординга через терминал,
  • Открыть dbt: Register dbt extension в command palette,
  • Использовать кнопку Get started в меню расширения.

Ниже описаны шаги для начала работы через кнопку Get started:

  1. В боковом меню нажмите на логотип dbt, чтобы открыть меню, и разверните раздел Get started.
  2. Нажмите на статус dbt Walkthrough, чтобы открыть приветственный экран.
    Экран приветствия расширения dbt для VS Code.Экран приветствия расширения dbt для VS Code.
  3. Последовательно выполните пункты для начала работы:
    • Открыть ваш dbt‑проект: Открывает проводник файлов для выбора dbt‑проекта, который вы хотите открыть с Fusion.
    • Проверить совместимость с Fusion: Запускает процесс обновления до Fusion. Если возникнут ошибки парсинга, можно дополнительно запустить dbt-autofix.
    • Изучить возможности: Открывает документацию с описанием возможностей расширения.
    • Зарегистрироваться: Запускает процесс регистрации для продолжения использования расширения после пробного периода.

Обновитесь до Fusion​

примечание

Если у вас уже установлен dbt Fusion Engine, для использования инструмента обновления требуется версия 2.0.0-beta.66 или выше.

Расширение dbt включает встроенный инструмент обновления, который пошагово помогает настроить Fusion и обновить dbt‑проект для поддержки всех его возможностей, а также устранить устаревший код. Чтобы начать:

  1. В боковой панели VS Code нажмите на логотип dbt.

  2. В открывшейся панели разверните раздел Get started и нажмите кнопку Get started.

    Панель помощи расширения dbt и мастер обновления.Панель помощи расширения dbt и мастер обновления.

Вы также можете запустить процесс вручную, открыв CLI и выполнив команду:

dbt init --fusion-upgrade

Инструмент обновления проведёт вас через процесс апгрейда Fusion с помощью серии вопросов:

  • У вас уже есть аккаунт dbt platform?: Если ответить Y, вы получите инструкции по загрузке профиля dbt platform для регистрации расширения. Ответ N пропустит этот шаг.

  • Готовы запустить dbtf init? (если файл profiles.yml отсутствует): Выполняется конфигурация dbt, включая подключение к хранилищу данных.

  • Готовы запустить dbtf debug? (если profiles.yml уже существует): Проверяет корректность конфигурации и возможность подключения к хранилищу данных.

  • Готовы запустить dbtf parse?: Проект dbt будет распарсен для проверки совместимости с Fusion.

    • Если во время парсинга возникнут проблемы, вам будет предложено запустить dbt-autofix. Без устранения ошибок процесс обновления не может быть продолжен.
      AI Agents

      В некоторых случаях dbt-autofix не может исправить все ошибки и требуется ручное вмешательство. Для таких ситуаций инструмент dbt-autofix предоставляет файл AI Agents.md, который позволяет использовать AI‑агентов для помощи в миграции после завершения работы dbt-autofix.

  • Готовы запустить ‘dbtf compile -static-analysis off’? (выполняется только после успешного parse): Компилирует проект без статического анализа, имитируя поведение dbt Core.

  • Готовы запустить ‘dbtf compile’?: Компилирует проект с полным статическим анализом Fusion, проверяя корректность SQL с учётом таблиц и колонок в вашем хранилище.

    Сообщение, которое вы получаете после завершения обновления проекта до движка dbt Fusion.Сообщение, которое вы получаете после завершения обновления проекта до движка dbt Fusion.

После завершения обновления вы готовы использовать все возможности dbt Fusion Engine!

Зарегистрируйте расширение​

После загрузки расширения и установки dbt Fusion Engine, вы должны зарегистрировать расширение dbt для VS Code в течение 14 дней после установки (или переустановки).

Ключевые моменты:

  • Расширение бесплатно для организаций до 15 пользователей (см. политику допустимого использования).
  • Регистрация связывает ваш редактор с аккаунтом dbt, чтобы вы могли продолжать пользоваться расширением после льготного периода.
  • Для этого не нужен проект dbt platform — достаточно аккаунта dbt.
  • Если на вашей машине есть корректный файл dbt_cloud.yml, расширение автоматически использует его и пропустит вход.
  • Если у вас уже есть аккаунт dbt (даже созданный много лет назад), вы попадёте в OAuth‑поток входа.
 Понимание регионов

Большинство пользователей могут войти через страницу регистрации в браузере из расширения для региона US1 по умолчанию. Если это работает, значит ваш аккаунт находится в регионе по умолчанию и вам не нужно учитывать другие регионы.

Используйте файл учётных данных (dbt_cloud.yml) вместо входа, если:

  • Вы не можете войти.
  • Ваша организация использует регион не по умолчанию (eu1, us2 и т. п.).
  • Вы предпочитаете учётные данные в файле.

Если вы не уверены, был ли у вас раньше аккаунт в US1, попробуйте войти или воспользоваться Forgot password на us1.dbt.com. Если ничего не находится, продолжайте с Регистрация через dbt_cloud.yml.

Выберите путь регистрации​

Путь регистрации расширения dbt для VS Code зависит от вашей ситуации. Выберите тот, который вам подходит:

Регистрация впервые​

Используйте это, если вы никогда раньше не создавали аккаунт dbt. Что нужно сделать: открыть команду, ввести имя и email, подтвердить email — и готово 🎉!

  1. Нажмите на приглашение к регистрации или откройте палитру команд (Ctrl + Shift + P (Windows/Linux) или Cmd + Shift + P (macOS)) и введите: dbt: Register dbt extension.
    Приглашение к регистрации расширения в VS Code.Приглашение к регистрации расширения в VS Code.
  2. В форме регистрации в браузере введите имя и email, затем нажмите Continue.
  3. Проверьте входящие: найдите письмо для подтверждения и нажмите ссылку подтверждения.
  4. После подтверждения вернитесь к браузерному потоку, чтобы завершить вход.
  5. Вы вернётесь в редактор и увидите Registered.
  6. Продолжайте по онбордингу Начало работы и запустите ваш dbt‑проект.

Примечание: для регистрации не нужен проект dbt platform; это только создаёт ваш аккаунт dbt.

Вход с существующим аккаунтом​

Используйте этот вариант, если у вас уже есть аккаунт dbt — включая старые или неактивные аккаунты. dbt автоматически обнаружит ваш аккаунт и файл dbt_cloud.yml, если он существует (скачивать файл не нужно). Удобно, если вы работаете на нескольких машинах.

  1. Нажмите на приглашение к регистрации или откройте палитру команд и введите: dbt: Register dbt extension.
  2. В форме регистрации в браузере внизу формы выберите Sign in.
  3. Введите email, связанный с вашим аккаунтом dbt, и нажмите Continue. Если вы не помните пароль, см. Восстановление доступа.
  4. Затем у вас будет возможность выбрать существующий аккаунт dbt.
  5. Выберите аккаунт, который хотите использовать, и нажмите Continue.
  6. Вы должны увидеть страницу, подтверждающую успешную регистрацию. Закройте вкладку и вернитесь в редактор, чтобы продолжить регистрацию.

Когда dbt_cloud.yml всё ещё может понадобиться:

  • Вам нужны учётные данные в файле для автоматизаций.
  • Вы на бесплатном тарифе Developer, и вашему процессу нужен локальный файл учётных данных для defer.
  • Этого требует ваш регион (например, eu1 или us2).

Восстановление доступа​

Выберите этот путь, если форма регистрации сообщает, что ваш email уже существует, но вы не помните пароль или ваш аккаунт заблокирован.

Чтобы сбросить пароль и войти через OAuth‑поток:

  1. На экране входа нажмите Forgot password.
  2. Введите email, связанный с вашим аккаунтом dbt.
  3. Проверьте почту и сбросьте пароль.
  4. Вернитесь на экран входа в браузере и завершите процесс входа.
  5. Если вы вошли, у вас появится возможность выбрать существующий аккаунт dbt.
  6. Выберите аккаунт, который хотите использовать, и нажмите Continue.
  7. Вы должны увидеть страницу, подтверждающую успешную регистрацию. Закройте вкладку и вернитесь в редактор, чтобы продолжить регистрацию.

Если вы всё ещё не можете войти:

Регистрация через dbt_cloud.yml​

Используйте этот вариант, если вы не можете войти в аккаунт dbt, ваша организация использует регион не по умолчанию (eu1, us2), или вашему процессу нужен файл учётных данных.

Что нужно сделать: скачать файл dbt_cloud.yml, положить его в каталог .dbt и запустить команду регистрации.

  1. Войдите в dbt platform и откройте Account settings → VS Code extension.

  2. В разделе Set up your credentials нажмите Download credentials, чтобы получить файл dbt_cloud.yml.

    Скачайте файл dbt_cloud.yml из аккаунта dbt platform.Скачайте файл dbt_cloud.yml из аккаунта dbt platform.

  3. Переместите файл в ваш каталог dbt:

    • macOS/Linux: ~/.dbt/dbt_cloud.yml
    • Windows: C:\Users\[username]\.dbt\

    Как создать/переместить каталог .dbt, см. этот FAQ.

  4. Вернитесь в VS Code, откройте палитру команд и введите: dbt: Register dbt extension.

  5. Расширение обнаружит файл учётных данных, и вы сможете продолжить процесс регистрации.

Детали поведения:

  • Если файл dbt_cloud.yml существует, он имеет приоритет над любым входом, и расширение использует его автоматически.
  • Если файла нет, вам предложат войти или добавить файл.

Настройка переменных окружения локально​

Этот раздел необязателен. Вам нужно настраивать переменные окружения локально только если ваш dbt‑проект использует переменные окружения, которые уже настроены в dbt platform.

Если ваш dbt‑проект использует переменные окружения, вы можете настроить их, чтобы использовать функции расширения. Подробнее см. на странице Configure environment variables.

Устранение неполадок​

Если у вас возникли какие‑либо проблемы, ознакомьтесь с разделом устранения неполадок ниже.

 Как создать директорию .dbt в корне и переместить файл dbt_cloud.yml

Если у вас ещё нет директории .dbt, рекомендуется выполнить следующие шаги, чтобы создать её. Если директория .dbt у вас уже есть, переместите файл dbt_cloud.yml внутрь неё. Ниже приведена справочная информация о директории .dbt:

  • Директория .dbt — это скрытая папка в корне вашей файловой системы. Она используется для хранения конфигурационных файлов dbt. Префикс . делает папку скрытой, поэтому по умолчанию она не отображается в Finder или File Explorer.
  • Чтобы увидеть скрытые файлы и папки, нажмите Command + Shift + G на macOS или Ctrl + Shift + G на Windows. Это откроет диалог «Go to Folder», в котором можно перейти к директории .dbt.

  1. Клонируйте репозиторий вашего dbt‑проекта локально.

  2. Используйте команду mkdir, указав имя папки, которую нужно создать.

    • Если вы используете macOS, добавьте префикс ~, чтобы создать папку .dbt в корне вашей файловой системы:
    mkdir ~/.dbt # macOS
    mkdir %USERPROFILE%\.dbt # Windows
 Я не вижу вкладку lineage в Cursor

Если вы используете расширение dbt для VS Code в Cursor, вкладка lineage лучше всего работает в режиме Editor и не отображается в режиме Agent. Если вы находитесь в режиме Agent и вкладка lineage не рендерится, просто переключитесь в режим Editor, чтобы просмотреть lineage таблиц и колонок вашего проекта.

 Настройки dbt platform

Если вы используете облачную платформу dbt, у вас есть конфигурация dbt-cloud: в файле dbt_project.yml, и при этом вы также используете dbt Mesh, необходимо указать ID проекта:

dbt-cloud:
  project-id: 12345 # Required

Если эта настройка указана некорректно, кросс‑платформенные ссылки не будут разрешаться, и при выполнении команд dbt будут возникать ошибки.

 Расширение dbt не активируется

Если расширение dbt успешно активировалось, вы увидите метку dbt Extension в строке состояния в левом нижнем углу редактора. Диагностическую информацию о расширении dbt можно посмотреть, нажав на кнопку dbt Extension.

Если метка dbt Extension отсутствует, скорее всего, расширение dbt не было установлено корректно. В этом случае попробуйте удалить расширение, перезапустить редактор и затем установить расширение заново.

Примечание: В VS Code можно «скрывать» элементы строки состояния. Проверьте, не скрыта ли метка dbt Extension: щёлкните правой кнопкой мыши по строке состояния в редакторе. Если в контекстном меню присутствует dbt Extension, значит расширение было установлено успешно.

 Ошибка Missing dbt LSP features

Если вы получаете сообщение об ошибке no active LSP for this workspace или не видите возможности dbt Language Server (LSP) в редакторе (например, автодополнение, переход к определению или всплывающие подсказки), сначала выполните общие шаги по устранению неполадок, описанные ранее.

Если вы убедились, что расширение dbt установлено корректно, но функции LSP по‑прежнему отсутствуют, попробуйте следующее:

  1. Проверьте версию расширения — убедитесь, что вы используете последнюю доступную версию расширения dbt:
    • откройте страницу Extensions в редакторе, или
    • перейдите на вкладку Output и посмотрите номер версии, или
    • выполните команду dbtf --version в терминале.
  2. Переустановите LSP — если версия корректна, переустановите LSP:
    1. Откройте Command Palette: Command + Shift + P (macOS) или Ctrl + Shift + P (Windows/Linux).
    2. Введите dbt: Reinstall dbt LSP и нажмите Enter.

Эта команда загрузит LSP и повторно активирует расширение, что должно устранить ошибку.

 Неподдерживаемая версия dbt

Если вы видите сообщение об ошибке о том, что используемая версия dbt не поддерживается, скорее всего, проблема связана с вашим окружением.

Проверьте настройку dbt Path в настройках VS Code. Если этот путь задан, убедитесь, что он указывает на корректный исполняемый файл dbt Fusion Engine.
При необходимости вы также можете установить dbt Fusion Engine напрямую, следуя этим инструкциям: Install the Fusion CLI

 Устранение ошибки 'dbt language server is not running in this workspace'

Чтобы устранить ошибку dbt language server is not running in this workspace, необходимо добавить папку с проектом dbt в workspace:

  1. В VS Code нажмите File в панели инструментов и выберите Add Folder to Workspace.
  2. Выберите папку проекта dbt, которую хотите добавить в workspace.
  3. Чтобы сохранить workspace, нажмите File, затем выберите Save Workspace As.
  4. Укажите расположение, в котором вы хотите сохранить workspace.

После этого ошибка должна исчезнуть, а ваш проект dbt будет открыт через соответствующий workspace. Дополнительную информацию о workspace см. в разделе Что такое Workspace в VS Code?.

Дополнительная информация о Fusion​

Fusion — это значительное обновление dbt. Хотя многие рабочие процессы, к которым вы привыкли, остаются без изменений, появляется множество новых идей, а также происходит отказ от ряда старых подходов. Ниже приведён список, охватывающий полный объём текущего релиза движка Fusion, включая вопросы реализации, установки, устаревших возможностей и ограничений:

Нашли ошибку?

0
Loading