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

Настройка локального окружения

Независимо от того, используете ли вы dbt platform или самостоятельно размещаете dbt, следуйте инструкциям на этой странице, чтобы:

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

Шаги немного различаются в зависимости от того, используете ли вы dbt platform или самостоятельно развернутый dbt.

  • dbt platform — Вы воспроизведете свою среду dbt platform локально, чтобы получить доступ к таким мощным возможностям, как Mesh, отложенное разрешение ссылок (deferral) и другим. Если в вашем проекте есть переменные окружения, вы также зададите их локально, чтобы использовать возможности расширения для VS Code.
  • Самостоятельное развертывание — Если вы самостоятельно развертываете dbt, у вас, скорее всего, уже настроены локальная среда и переменные окружения. Используйте эту страницу, чтобы убедиться, что ваша существующая локальная среда и переменные окружения корректно работают с расширением для VS Code.

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

Подготовить локальное окружение​

В этом разделе мы пошагово разберём, как подготовить локальное окружение для расширения dbt в VS Code. Если вы пользователь dbt platform и установили расширение VS Code, выполните эти шаги. Если вы используете self‑hosted вариант, у вас, скорее всего, уже есть локальная настройка и переменные окружения, но вы можете проверить это, следуя данным шагам.

  1. Клонируйте репозиторий вашего проекта dbt у вашего Git-провайдера на локальный компьютер. Если вы используете dbt platform, клонируйте тот же репозиторий, который подключён к вашему проекту.
  2. Убедитесь, что у вас есть файл profiles.yml для dbt. Этот файл определяет подключение к вашему хранилищу данных. Если его нет, выполните dbt init в терминале, чтобы настроить адаптер.
  3. Проверьте profiles.yml и конфигурацию проекта, выполнив dbt debug.
  4. Добавьте файл dbt_cloud.yml из настроек аккаунта dbt platform:
    • Перейдите в Your profile → VS Code Extension → Download credentials.
    • Поместите скачанный файл в каталог ~/.dbt/. Это зарегистрирует расширение и подключит его к dbt platform, а также включит функции платформы, такие как Mesh и отложенное разрешение ссылок (deferral). Структура файла и обязательные поля описаны в разделе dbt_cloud.yml.
    • Убедитесь, что project-id в блоке dbt-cloud файла dbt_project.yml соответствует проекту, над которым вы работаете.
  5. Проверьте подключение с вашего рабочего компьютера (например, выполнив dbt debug в терминале). Ваш локальный компьютер подключается напрямую к хранилищу данных и Git.
    • Пользователям dbt platform: убедитесь, что доступ с вашего ноутбука или через VPN разрешён; IP-адреса dbt platform больше не применяются. При возникновении проблем обратитесь к администратору.
    • Пользователям dbt v1: скорее всего, это уже настроено.
  6. (Необязательно) Если ваш проект использует переменные окружения, найдите их в dbt platform и задайте их в VS Code или Cursor.
    • Пользователям dbt platform: скопируйте все переменные окружения с вкладки Deploy → Environments → Environment variables в dbt platform. Замаскированные секреты скрыты. Обратитесь к администратору, чтобы получить их значения.
    Вкладка переменных окруженияВкладка переменных окружения

Задайте переменные окружения локально​

Переменные окружения используются для аутентификации и конфигурации.

Этот раздел наиболее актуален для пользователей расширения dbt для VS Code и dbt platform, у которых переменные окружения настроены как часть рабочей среды. Если вы используете dbt локально, вы также можете установить расширение для VS Code и пользоваться его возможностями и действиями — при этом настраивать эти переменные может не потребоваться, если только ваша конфигурация явно этого не требует.

В таблице ниже показаны различные варианты и случаи, когда их следует использовать:

МестоВлияет наСостояние сессииКогда использовать
Профиль оболочки Терминал✅ ПостоянноПеременные остаются активными глобально и доступны во всех сеансах терминала.
Настройки VS Code/CursorМеню расширения + LSP✅ Для каждого профиля VS Code/CursorРабочие процессы только в редакторе с использованием действий из меню расширения.
Сеанс терминалаТолько текущий терминал❌ ВременноРазовое тестирование.
подсказка

Если вы хотите использовать и меню расширения VS Code, и терминал для запуска команд dbt, определите переменные и в shell‑профиле, и в настройках VS Code/Cursor. Так они будут доступны глобально в терминале и внутри VS Code/Cursor.

Настройка на уровне ОС или оболочки​

Определите переменные один раз на уровне ОС или оболочки, чтобы они были доступны во всех сеансах терминала. Даже если вы закроете окно терминала, переменные останутся вам доступны.

  1. Откройте файл конфигурации shell в текстовом редакторе с помощью следующих команд (если файл не существует, создайте его, например с помощью vi ~/.zshrc или vi ~/.bashrc): 
    open -e ~/.zshrc ## for zsh (macOS)
    nano ~/.bashrc ## for bash (Linux or older macOS)
  2. В открывшемся файле добавьте ваши переменные окружения. Например:
    • Для zsh (macOS): 
          ## ~/.zshrc 
          export DBT_ENV_VAR1="my_value"
          export DBT_ENV_VAR2="another_value"
    • Для bash (Linux или более старых версий macOS): 
          ## ~/.bashrc or ~/.bash_profile
          export DBT_ENV_VAR1="my_value"
          export DBT_ENV_VAR2="another_value"
  3. Сохраните файл.
  4. Запустите новую shell‑сессию, закрыв и открыв терминал, либо выполнив source ~/.zshrc или source ~/.bashrc в терминале.
  5. Проверьте переменные, выполнив echo $DBT_ENV_VAR1 и echo $DBT_ENV_VAR2 в терминале.

Если значение выводится в терминал, всё настроено правильно. Эти переменные теперь будут доступны:

  • Во всех будущих терминальных сессиях
  • Для всех команд dbt, запускаемых в терминале

О поддержке файлов .env​

dbt и расширение dbt для VS Code могут автоматически считывать переменные окружения из файла .env в текущем рабочем каталоге (папке, в которую вы переходите с помощью cd и из которой запускаете команды dbt в терминале), если такой файл существует. Переменные окружения, заданные в файле .env, доступны при запуске команд dbt в терминале и при использовании действий меню расширения.

При определении переменных окружения в файле .env учитывайте следующее:

  • Файл .env позволяет удобно задавать переменные окружения, которые работают как в CLI, так и в расширении для VS Code.
  • Рекомендуем размещать файл .env в корневом каталоге проекта и запускать команды dbt из этого каталога, поскольку файл загружается только из текущего рабочего каталога. Загрузка файла не поддерживает флаг --project-dir или переменную окружения (Версии dbt: v1.11 и новее) DBT_ENGINE_PROJECT_DIR, и dbt не будет искать файл в корневом каталоге проекта, если вы запускаете команды из другого каталога.
  • Добавьте .env в файл .gitignore, чтобы конфиденциальные учетные данные не попали в репозиторий при коммите.
  • Переменные окружения, заданные непосредственно в командной оболочке (например, export DBT_ENV_VAR=value), имеют приоритет над значениями, определенными в файле .env.

Настройка в параметрах расширения VS Code​

Чтобы использовать действия меню и кнопки расширения dbt, можно настроить переменные окружения непосредственно в интерфейсе пользовательских настроек VS Code или в файле .env в текущем рабочем каталоге. Это относится как к вашим пользовательским переменным, так и к любым автоматическим переменным dbt platform (например, DBT_CLOUD_ENVIRONMENT_NAME), от которых зависит ваш проект.

  • Настройте переменные в пользовательских настройках VS Code или в файле .env, чтобы расширение могло их распознать. Например, они будут доступны при использовании функций на базе LSP, действия «Show build menu» и других возможностей.
  • VS Code не наследует переменные, заданные в терминале VS Code или во внешних командных оболочках.
  • Терминал использует системные переменные окружения и не наследует переменные, заданные в настройках расширения dbt для VS Code. Например, при запуске команды dbt в терминале переменные расширения dbt для VS Code не будут ни считываться, ни использоваться.

Чтобы настроить переменные окружения в VS Code/Cursor:

  1. Откройте Command Palette (Cmd + Shift + P на Mac, Ctrl + Shift + P на Windows/Linux).
  2. Выберите Preferences: Open User Settings в выпадающем списке.
  3. Откройте страницу VS Code user settings.
  4. Найдите dbt.environmentVariables.
  5. В разделе dbt:Environment Variables добавьте нужные переменные и значения.
  6. Нажмите Ok, чтобы сохранить изменения.
  7. Перезагрузите расширение VS Code, чтобы применить изменения: откройте Command Palette и выберите Developer: Reload Window.
  8. Проверьте изменения, запустив команду dbt и изучив вывод.

Настройка в сеансе терминала​

Переменные окружения можно задать прямо в терминальной сессии с помощью команды export. Важно учитывать следующее:

  • Переменные будут видны только командам, запущенным в рамках этой сессии терминала.
  • Они действуют только в текущей сессии — при открытии нового терминала значения будут потеряны.
  • Встроенные кнопки и меню расширения dbt для VS Code эти переменные использовать не будут.

Чтобы задать переменные окружения в терминальной сессии:

  1. Выполните следующую команду в терминале, заменив DBT_ENV_VAR1 и test1 на ваши значения.

    export DBT_ENV_VAR1=test1

  2. Проверьте изменения, запустив команду dbt и изучив вывод.

Настройки расширения dbt​

После установки расширения dbt и настройки локального окружения вы можете дополнительно сконфигурировать его под свой рабочий процесс разработки:

  1. Откройте настройки VS Code, нажав Ctrl+, (Windows/Linux) или Cmd+, (Mac).
  2. Введите dbt в строку поиска. На этой странице можно настроить параметры расширения в соответствии с вашими потребностями.
Настройки расширения dbt в настройках VS Code.Настройки расширения dbt в настройках VS Code.

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

НастройкаОписание
dbt.fusionPathПуть к исполняемому файлу v2. Расширение запускает языковой сервер через этот файл (dbt-fusion lsp). Укажите этот путь, если устанавливаете v2 вручную — например, в изолированной среде — вместо того чтобы позволить расширению загрузить его.
dbt.badReleasesManifestPathПуть к локальной копии манифеста заведомо проблемных выпусков. Используйте эту настройку, если у вас нет исходящего доступа к сети и вы распространяете манифест вместе с комплектом исполняемых файлов (например, при установке в изолированной среде).
dbt.environmentVariablesПеременные окружения, которые расширение передаёт dbt. См. раздел Настройка в параметрах расширения VS Code.
Переход с отдельного исполняемого файла языкового сервера

В предыдущих версиях расширения использовались отдельные настройки dbt.cliPath и dbt.lspPath для двух разных исполняемых файлов. В текущих версиях используется единая настройка dbt.fusionPath, поскольку в dbt v2 CLI и языковой сервер поставляются в одном исполняемом файле. Если ранее вы настроили dbt.lspPath, перенесите этот путь в dbt.fusionPath. Подробнее см. в разделе Совместимость версий.

Ассоциации файлов и другие расширения​

Расширение dbt не зависит от ассоциаций файлов .sql. Оно активируется при обнаружении вашего dbt_project.yml, поэтому функции LSP — такие как автодополнение, переход к определению и IntelliSense с учётом структуры базы данных — работают независимо от того, назначен ли вашим файлам тип sql или jinja-sql. Разница между этими двумя типами заключается только в подсветке синтаксиса и значке файла.

Ассоциация имеет значение для других расширений. Любое расширение, которое обрабатывает тип файлов sql, — будь то Snowflake, SQL Server или другой инструмент для работы с базами данных, — может перехватывать ваши файлы dbt и переопределять функции IntelliSense, которые иначе предоставляло бы расширение dbt. Например, расширение Snowflake обрабатывает только файлы, связанные с типом snowflake-sql. Поэтому snowflake-sql — неподходящая ассоциация для ваших файлов dbt: она передаёт их расширению Snowflake вместо того, чтобы обрабатывать их как файлы dbt. Если у вас установлено несколько расширений для работы с SQL, стоит проверить, какое из них обрабатывает ваши файлы .sql, чтобы избежать неожиданного поведения.

Если вы хотите использовать оба расширения, храните файлы разовых запросов в отдельном каталоге, исключённом из отслеживания Git, и ограничьте ассоциацию Snowflake только этим путём:

{
  "files.associations": {
    "**/snowflake_sandbox/*.sql": "snowflake-sql",
    "*.sql": "sql"
  }
}

Следующие шаги​

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

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

0
Loading