# Пакеты

Программисты часто модульно организуют код в библиотеки. Эти библиотеки помогают программистам работать более эффективно: они могут тратить больше времени на уникальную бизнес-логику и меньше времени на реализацию кода, который кто-то другой уже довел до совершенства.

Разработчики программного обеспечения часто организуют код в виде библиотек. Эти библиотеки помогают программистам работать эффективнее: уделять больше времени своей уникальной бизнес-логике и меньше — реализации кода, на совершенствование которого кто-то другой уже потратил время.

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

* преобразование данных из наборов данных SaaS с единообразной структурой, например:

  * объединение просмотров страниц из [Snowplow](https://hub.getdbt.com/dbt-labs/snowplow/latest/) или [Segment](https://hub.getdbt.com/dbt-labs/segment/latest/) в сеансы
  * приведение данных о расходах из [AdWords](https://hub.getdbt.com/dbt-labs/adwords/latest/) или [Facebook Ads](https://hub.getdbt.com/dbt-labs/facebook_ads/latest/) к единому формату.

* написание макросов dbt, выполняющих схожие функции, например:

  * [генерация SQL](https://github.com/dbt-labs/dbt-utils#sql-helpers) для объединения двух отношений, разворота столбцов или создания суррогатного ключа (суррогатный ключ)
  * создание [пользовательских тестов схемы](https://github.com/dbt-labs/dbt-utils#schema-tests)
  * написание [аудиторских запросов](https://hub.getdbt.com/dbt-labs/audit_helper/latest/)

* создание моделей и макросов для конкретного инструмента из вашего стека обработки данных, например:

  * Модели для анализа прав доступа в [Redshift](https://hub.getdbt.com/dbt-labs/redshift/latest/).
  * Макросы для работы с данными, загруженными с помощью [Stitch](https://hub.getdbt.com/dbt-labs/stitch_utils/latest/).

* подготовка неструктурированных данных, чтобы ИИ-агенты могли находить их, доверять им и ссылаться на них, например:
  * разбиение расшифровок звонков или обращений в службу поддержки на фрагменты, создание эмбеддингов и семантический поиск с помощью пакета [dbt\_context\_engineering](https://hub.getdbt.com/dbt-labs/dbt_context_engineering/latest/). Подробнее см. в [статье блога о dbt\_context\_engineering](https://docs.getdbt.com/blog/dbt-context-engineering).

*Пакеты* dbt — это, по сути, самостоятельные проекты dbt с моделями, макросами и другими ресурсами, предназначенными для решения определённого круга задач. Когда вы как пользователь dbt добавляете пакет в свой проект, все ресурсы пакета становятся частью вашего проекта. Это означает следующее:

* Модели из пакета будут материализованы при выполнении `dbt run`.
* Вы можете использовать `ref` в собственных моделях, чтобы ссылаться на модели из пакета.
* Вы можете использовать `source`, чтобы ссылаться на источники из пакета.
* Вы можете использовать макросы из пакета в собственном проекте.
* Важно отметить, что определение и установка пакетов dbt отличаются от [определения и установки пакетов Python](https://docs.getdbt.tech/docs/build/python-models.md#using-pypi-packages)

## Варианты использования

Следующая настройка подойдет для любого dbt-проекта:

* Добавьте [зависимости от пакетов](https://docs.getdbt.tech/docs/mesh/govern/project-dependencies.md#about-packagesyml-and-dependenciesyml) в `packages.yml`
* Добавьте [зависимости от проектов](https://docs.getdbt.tech/docs/mesh/govern/project-dependencies.md#about-packagesyml-and-dependenciesyml) в `dependencies.yml`

Однако, возможно, вы сможете объединить всё в один файл `dependencies.yml`. Прочитайте следующий раздел, чтобы узнать больше.

#### О `packages.yml` и `dependencies.yml`

Файл `dependencies.yml` может содержать оба типа зависимостей: зависимости от пакетов ("package") и от проектов ("project").

* [Зависимости от пакетов](https://docs.getdbt.tech/docs/build/packages.md#how-do-i-add-a-package-to-my-project) позволяют добавлять в ваш проект исходный код из dbt-проекта другого автора — как библиотеку.
* Зависимости от проектов (project dependencies) предоставляют другой способ строить решения поверх чужой работы в dbt.

Для приватных пакетов без токенов Jinja можно использовать [встроенную поддержку приватных пакетов](https://docs.getdbt.tech/docs/build/packages.md#native-private-packages) в `packages.yml` или `dependencies.yml`.

Если вашему проекту dbt не требуется Jinja в спецификациях пакетов, вы можете переименовать `packages.yml` в `dependencies.yml`. Если вам требуется Jinja в спецификациях пакетов (например, для переменной окружения или [метода с Git-токеном](https://docs.getdbt.tech/docs/build/packages.md#git-token-method)):

* В dbt v1 продолжайте использовать `packages.yml`. dbt v1 не обрабатывает Jinja в `dependencies.yml`.
* В dbt v2 можно использовать Jinja в `dependencies.yml`. Если проект должен работать и в dbt v1, рекомендуется использовать `packages.yml`.

Полную таблицу поддержки см. в разделе [Поддержка Jinja по типам файлов](https://docs.getdbt.tech/reference/jinja-file-support.md). Используйте приведённые ниже переключатели, чтобы разобраться в различиях и определить, когда использовать `dependencies.yml` или `packages.yml` (или оба файла). Дополнительную информацию см. в разделе [Часто задаваемые вопросы](https://docs.getdbt.tech/docs/mesh/govern/project-dependencies.md#faqs).

 Когда использовать зависимости проектов

Зависимости проектов предназначены для работы с [dbt Mesh](https://docs.getdbt.tech/best-practices/how-we-mesh/mesh-1-intro.md) и [межпроектными ссылками](https://docs.getdbt.tech/docs/mesh/govern/project-dependencies.md#how-to-write-cross-project-ref):

* Используйте `dependencies.yml`, когда нужно настроить межпроектные ссылки между разными проектами dbt, особенно при использовании dbt Mesh.
* Используйте `dependencies.yml`, когда хотите включить в зависимости своего проекта как другие проекты, так и неприватные пакеты dbt.
* Используйте `dependencies.yml` для упорядочения зависимостей и упрощения их сопровождения, если вы используете одновременно [межпроектные ссылки](https://docs.getdbt.tech/docs/mesh/govern/project-dependencies.md#how-to-write-cross-project-ref) и [пакеты из dbt Hub](https://hub.getdbt.com/). Это позволяет сократить количество YAML-файлов, необходимых для управления зависимостями.

 Когда использовать package dependencies

Package dependencies позволяют добавлять в ваш проект исходный код из dbt-проекта другого автора — как библиотеку:

* Если вы используете только пакеты, например из [dbt Hub](https://hub.getdbt.com/), продолжайте использовать `packages.yml`.
* Используйте `packages.yml`, если хотите загружать пакеты dbt, например проекты dbt, в свой корневой или родительский проект dbt. Обратите внимание, что этот файл не участвует в рабочем процессе dbt Mesh.
* Используйте `packages.yml`, чтобы включать пакеты в зависимости вашего проекта. Это касается как общедоступных пакетов, например из [dbt Hub](https://hub.getdbt.com/), так и приватных пакетов. Теперь dbt поддерживает [нативную работу с приватными пакетами](https://docs.getdbt.tech/docs/build/packages.md#native-private-packages).
* По историческим причинам [`packages.yml` поддерживает рендеринг Jinja](https://docs.getdbt.tech/docs/build/dbt-tips.md#yaml-tips), что позволяет создавать динамические конфигурации. Это может быть полезно, если вам нужно подставлять значения из переменных окружения в спецификации пакетов, например при использовании [метода с токеном Git](https://docs.getdbt.tech/docs/build/packages.md#git-token-method). dbt v2 также поддерживает Jinja в `dependencies.yml`; см. [поддержку Jinja по типам файлов](https://docs.getdbt.tech/reference/jinja-file-support.md).

Ранее для использования приватных Git-репозиториев в dbt приходилось применять обходной путь: встраивать Git token с помощью Jinja. Это неидеально, потому что требует дополнительных шагов — например, создавать пользователя и делиться Git token. Мы добавили поддержку [native private packages](https://docs.getdbt.tech/docs/build/packages.md#native-private-packages), чтобы решить эту проблему.

## Как создать пакет?

Создание пакетов — это продвинутый сценарий использования dbt, однако на практике это может быть относительно простой задачей. Единственное строгое требование — наличие файла [`dbt_project.yml`](https://docs.getdbt.tech/reference/dbt_project.yml.md).

Наиболее распространённые сценарии использования пакетов:

* Распространение [models](https://docs.getdbt.tech/docs/build/models.md) для повторного использования в нескольких проектах.
* Распространение [macros](https://docs.getdbt.tech/docs/build/jinja-macros.md) для повторного использования в нескольких проектах.

Обратите внимание, что пакеты могут быть [приватными](#private-packages) — их не обязательно публиковать в открытом доступе. Приватные пакеты можно размещать в собственном Git‑провайдере (например, GitHub или GitLab).

Инструкции по созданию пакетов dbt и дополнительную информацию вы найдёте в нашем руководстве [Building dbt packages](https://docs.getdbt.tech/guides/building-packages.md?step=1).

## Как добавить пакет в проект?

1. Добавьте в ваш dbt‑проект файл с именем `dependencies.yml` или `packages.yml`. Он должен находиться на том же уровне, что и файл `dbt_project.yml`.
2. Укажите пакет(ы), которые вы хотите добавить, используя один из поддерживаемых синтаксисов, например:

```yaml
packages:
  - package: dbt-labs/snowplow
    version: 0.7.0

  - git: "https://github.com/dbt-labs/dbt-utils.git"
    revision: 0.9.2

  - local: /opt/dbt/redshift
```

По умолчанию [`packages-install-path`](https://docs.getdbt.tech/reference/project-configs/packages-install-path.md) — это `dbt_packages`.

3. Запустите `dbt deps`, чтобы установить пакет(ы). Пакеты устанавливаются в директорию `dbt_packages` — по умолчанию эта директория игнорируется git, чтобы избежать дублирования исходного кода пакета.

## Как указать пакет?

Вы можете указать пакет, используя один из следующих методов, в зависимости от того, где хранится ваш пакет.

### Hub-пакеты (рекомендуется)

dbt Labs предоставляет [Package hub](https://hub.getdbt.com), реестр для пакетов dbt, в качестве услуги для сообщества dbt, но не сертифицирует и не подтверждает целостность, работоспособность, эффективность или безопасность любых пакетов. Пожалуйста, прочитайте [отказ от ответственности dbt Labs Package](https://hub.getdbt.com/disclaimer/) перед установкой hub-пакетов.

Вы можете установить доступные hub-пакеты следующим образом:

packages.yml

```yaml
packages:
  - package: dbt-labs/snowplow
    version: 0.7.3 # номер версии
```

Для hub-пакетов требуется указание версии — вы можете найти последний номер релиза на dbt Hub. Поскольку hub-пакеты используют [семантическое версионирование](https://semver.org/), мы рекомендуем закрепить ваш пакет на последней патч-версии из конкретного минорного релиза, например:

```yaml
packages:
  - package: dbt-labs/snowplow
    version: [">=0.7.0", "<0.8.0"]
```

`dbt deps` "закрепляет" каждый пакет по умолчанию. Подробности см. в разделе ["Закрепление пакетов"](#pinning-packages).

По возможности, мы рекомендуем устанавливать пакеты через dbt Hub, так как это позволяет dbt обрабатывать дублирующиеся зависимости. Это полезно в таких ситуациях, как:

* Ваш проект использует как пакеты dbt-utils, так и Snowplow, и пакет Snowplow *также* использует пакет dbt-utils.
* Ваш проект использует как пакеты Snowplow, так и Stripe, оба из которых используют пакет dbt-utils.

В сравнении, другие методы установки пакетов не могут обрабатывать дублирующийся пакет dbt-utils.

Опытные пользователи могут разместить внутреннюю версию хаба пакетов на основе [этого репозитория](https://github.com/dbt-labs/hub.getdbt.com), задав переменную окружения (Версии dbt: v1.11 и новее) `DBT_ENGINE_PACKAGE_HUB_URL`.

#### Предрелизные версии

Некоторые поддерживающие пакеты могут захотеть выложить предрелизные версии пакетов на dbt Hub, чтобы протестировать новую функциональность или совместимость с новой версией dbt. Предрелизная версия обозначается суффиксом, таким как `a1` (первая альфа), `b2` (вторая бета) или `rc3` (третий кандидат на релиз).

По умолчанию, `dbt deps` не будет включать предрелизные версии при разрешении зависимостей пакетов. Вы можете включить установку предрелизов одним из двух способов:

* Явно указав предрелизную версию в ваших критериях `version`
* Установив `install_prerelease` в `true` и предоставив совместимый диапазон версий

Например, обе следующие конфигурации успешно установят `0.4.5-a2` для [`dbt_artifacts` пакета](https://hub.getdbt.com/brooklyn-data/dbt_artifacts/latest/):

```yaml
packages:
  - package: brooklyn-data/dbt_artifacts
    version: 0.4.5-a2
```

```yaml
packages:
  - package: brooklyn-data/dbt_artifacts
    version: [">=0.4.4", "<0.4.6"]
    install_prerelease: true
```

### Git-пакеты

Пакеты, хранящиеся на Git-сервере, могут быть установлены с использованием синтаксиса `git`, например:

packages.yml

```yaml
packages:
  - git: "https://github.com/dbt-labs/dbt-utils.git" # git URL
    revision: 0.9.2 # имя тега или ветки
```

Добавьте URL для пакета с помощью `Git` и при необходимости укажите ревизию. Ревизией может быть:

* имя ветки
* тег релиза
* конкретный коммит (полный 40-символьный хэш)

Пример ревизии, указывающей 40-символьный хэш:

```yaml
packages:
  - git: "https://github.com/dbt-labs/dbt-utils.git"
    revision: 4e28d6da126e2940d17f697de783a717f2503188
```

По умолчанию, `dbt deps` "закрепляет" каждый пакет. Подробности см. в разделе ["Закрепление пакетов"](#pinning-packages).

### URL tarball, размещённый во внутренней инфраструктуре

В некоторых организациях действуют требования безопасности, согласно которым ресурсы можно загружать только из внутренних сервисов. Чтобы обеспечить установку пакетов из таких сред размещения, как Artifactory или бакеты облачных хранилищ, dbt позволяет устанавливать пакеты по URL-адресам tarball-архивов, размещённых во внутренней инфраструктуре.

Некоторые организации имеют требования безопасности, чтобы загружать ресурсы только из внутренних сервисов. Чтобы удовлетворить необходимость установки пакетов из размещенных сред, таких как Artifactory или облачные хранилища, dbt Core позволяет устанавливать пакеты из внутренне размещенных URL-адресов tarball.

```yaml
packages:
  - tarball: https://codeload.github.com/dbt-labs/dbt-utils/tar.gz/0.9.6
    name: 'dbt_utils'
```

Где `name: 'dbt_utils'` указывает подпапку `dbt_packages`, которая создается для установки исходного кода пакета.

## Приватные пакеты

### Встроенная поддержка приватных пакетов

Встроенная поддержка приватных пакетов позволяет устанавливать пакеты из [поддерживаемых](#prerequisites) приватных репозиториев Git с помощью ключа `private`, без настройки [токена](#git-token-method) или указания полного Git URL. Это упрощает настройку и сокращает объём работы по управлению учётными данными.

* dbt platform: использует существующую [интеграцию](https://docs.getdbt.tech/docs/platform/git/configure-git.md) с Git для аутентификации.
* При локальном использовании dbt v2 или dbt v1.12+: используется конфигурация SSH вашей системы. Требуется [`provider`](#using-the-provider-key).

#### Предварительные условия

* **dbt platform**: В разделе **Integrations** ваших **Account settings** должен быть настроен один из следующих провайдеров Git:

  * **[GitHub](https://docs.getdbt.tech/docs/platform/git/connect-github.md)**
  * **[Azure DevOps](https://docs.getdbt.tech/docs/platform/git/connect-azure-devops.md)**
    * Используйте путь `org/project/repo` с провайдером `ado`.
  * **[GitLab](https://docs.getdbt.tech/docs/platform/git/connect-gitlab.md)**
    * Каждый репозиторий GitLab с приватными пакетами также должен быть проектом dbt platform.

* **Локальное использование dbt v2 или dbt v1.12+**: На вашем компьютере должен быть настроен SSH-ключ для соответствующего Git-провайдера, а в конфигурацию пакетов необходимо включить [ключ `provider`](#using-the-provider-key).

#### Конфигурация

Используйте ключ `private` в файле `packages.yml` или `dependencies.yml`, чтобы клонировать репозитории пакетов с помощью существующей Git-интеграции dbt без необходимости выпускать токен доступа или создавать переменную окружения dbt.

packages.yml

```yaml
packages:
  - private: dbt-labs/awesome_repo # your-org/your-repo path
    provider: "github" # Supported values: "github", "gitlab", "ado"
  - package: normal packages
  [...]
```

dependencies.yml

```yaml
packages:
  - private: dbt-labs/awesome_repo # your-org/your-repo path
    provider: "github" # Supported values: "github", "gitlab", "ado"
```

Ограничения Azure DevOps

У встроенной интеграции с приватными пакетами Azure DevOps есть ограничения. Разверните раздел, чтобы узнать подробнее.

 Ограничения встроенной поддержки приватных пакетов в Azure DevOps

1. Используйте провайдера `ado` и укажите путь `org/project/repo` в ключе `private`.

   packages.yml

   ```yaml
   packages:
     - private: my-org/my-project/my-repo
       provider: "ado"
   ```

2. На dbt platform установка приватного пакета может завершиться ошибкой, если пакет находится в другом проекте Azure DevOps, чем задание, которое его устанавливает. Это особенно вероятно, если к аккаунту подключено много проектов Azure DevOps:

   * Во время выполнения задания dbt platform может использовать до 32 КБ данных аутентификации Azure DevOps. При превышении лимита доступно только подключение текущего проекта. Поэтому `dbt deps` не сможет получить пакеты из других проектов и завершится ошибкой.

   * Сократите число проектов Azure DevOps, подключённых к аккаунту, и повторно запустите `dbt deps`. Допустимое число проектов зависит от структуры организации Azure DevOps и числа репозиториев.

   Это ограничение не влияет на локальную разработку с dbt v1 или dbt v2, если вы клонируете приватные пакеты по SSH.

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

Вы можете закреплять версии приватных пакетов так же, как и у обычных пакетов dbt:

```yaml
packages:
  - private: dbt-labs/awesome_repo
    revision: "0.9.5" # Закрепить на теге, ветке или полном 40-символьном хэше коммита
```

#### Использование ключа `provider`

Добавьте ключ `provider`, если:

* Вы используете несколько интеграций с Git или используете dbt v2.
* Вы используете dbt v2 локально (через [CLI dbt v2](https://docs.getdbt.tech/docs/local/install-dbt.md?version=2) или [расширение для VS Code](https://docs.getdbt.tech/docs/local/install-dbt.md?version=2)) (обязательно).
* Вы используете dbt версии 1.12 или новее для клонирования по SSH (обязательно).

```yaml
packages:
  - private: dbt-labs/awesome_repo
provider: "github" # Поддерживаемые значения: "github", "gitlab", "ado"
```

dbt v1 и dbt v2 используют значение `provider`, чтобы сформировать правильный SSH URL для клонирования в зависимости от провайдера:

| Провайдер | Формат SSH URL                              |
| --------- | ------------------------------------------- |
| `github`  | `git@github.com:org/repo.git`               |
| `gitlab`  | `git@gitlab.com:org/repo.git`               |
| `ado`     | `git@ssh.dev.azure.com:v3/org/project/repo` |

dbt v1 и dbt v2 используют конфигурацию SSH вашей системы для аутентификации и клонирования приватного репозитория. Если команда `git clone` для приватного репозитория пакета работает в вашей системе, установка приватного пакета также должна работать.

### Метод с использованием SSH-ключа (только CLI)

примечание

В этом методе используется ключ `git:` с полным SSH URL, в отличие от [встроенного механизма приватных пакетов](#native-private-packages), в котором используется ключ `private:`. Для большинства сценариев рекомендуется встроенный механизм приватных пакетов, поскольку он упрощает настройку.

Если вы используете командную строку, приватные пакеты можно клонировать по SSH с помощью SSH-ключа.

При использовании SSH-ключей для аутентификации на удалённом git-сервере вам не нужно каждый раз вводить имя пользователя и пароль. Подробнее об SSH-ключах, их создании и добавлении у вашего git-провайдера читайте здесь: [Github](https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh) и [GitLab](https://docs.gitlab.com/ee/user/ssh.html).

Когда вы используете SSH-ключи для аутентификации на вашем удаленном сервере git, вам не нужно вводить ваше имя пользователя и пароль каждый раз. Подробнее о SSH-ключах, как их сгенерировать и как добавить их в ваш git-провайдер, читайте здесь: [Github](https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh) и [GitLab](https://docs.gitlab.com/ee/user/ssh.html).

packages.yml

```yaml
packages:
  - git: "git@github.com:dbt-labs/dbt-utils.git" # git SSH URL
```

Если вы используете dbt platform, метод с SSH-ключом не будет работать, но вы можете использовать [встроенную поддержку приватных пакетов](#native-private-packages) или [метод с токеном Git по HTTPS](https://docs.getdbt.tech/docs/build/packages.md#git-token-method).

### Метод Git-токена

примечание

[Нативная поддержка приватных пакетов](#native-private-packages) — рекомендуемый подход для GitHub, GitLab и Azure DevOps. Метод с использованием токена Git по-прежнему работает в dbt v1, dbt v2 и dbt platform, но требует создания персонального токена доступа. Он остаётся поддерживаемым способом для пользователей dbt v1, которым необходимо клонирование по HTTPS.

Этот метод позволяет пользователю клонировать через HTTPS, передавая git-токен через переменную окружения. Будьте осторожны с датой истечения срока действия любого токена, который вы используете, так как истекший токен может привести к сбою запланированного запуска. Кроме того, пользовательские токены могут создать проблему, если пользователь когда-либо потеряет доступ к конкретному репозиторию.

Использование dbt

Если вы используете dbt, необходимо соблюдать соглашения об именовании переменных окружения. Переменные окружения в dbt должны иметь префикс `DBT_` или `DBT_ENV_SECRET`. Имена переменных окружения записываются в верхнем регистре и чувствительны к регистру. При обращении к `{{env_var('DBT_KEY')}}` в коде вашего проекта имя должно в точности совпадать с именем переменной, заданным в пользовательском интерфейсе dbt.

В GitHub:

packages.yml

```yaml
packages:
  # используйте этот формат при доступе к вашему репозиторию через токен приложения github
  - git: "https://{{env_var('DBT_ENV_SECRET_GIT_CREDENTIAL')}}@github.com/dbt-labs/awesome_repo.git" # git HTTPS URL

  # используйте этот формат при доступе к вашему репозиторию через классический личный токен доступа
  - git: "https://{{env_var('DBT_ENV_SECRET_GIT_CREDENTIAL')}}@github.com/dbt-labs/awesome_repo.git" # git HTTPS URL
 
   # используйте этот формат при доступе к вашему репозиторию через личный токен доступа с тонкой настройкой (иногда требуется имя пользователя)
  - git: "https://GITHUB_USERNAME:{{env_var('DBT_ENV_SECRET_GIT_CREDENTIAL')}}@github.com/dbt-labs/awesome_repo.git" # git HTTPS URL
```

Подробнее о создании персонального токена доступа GitHub читайте [здесь](https://docs.github.com/en/enterprise-server@3.1/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token). Вы также можете использовать [токен](https://docs.github.com/en/rest/reference/apps#create-an-installation-access-token-for-an-app) установки приложения GitHub App.

В GitLab:

packages.yml

```yaml
packages:
  - git: "https://{{env_var('DBT_USER_NAME')}}:{{env_var('DBT_ENV_SECRET_DEPLOY_TOKEN')}}@gitlab.example.com/dbt-labs/awesome_project.git" # git HTTPS URL
```

Подробнее о создании токена развертывания GitLab читайте [здесь](https://docs.gitlab.com/ee/user/project/deploy_tokens/#creating-a-deploy-token) и о том, как правильно построить ваш HTTPS URL [здесь](https://docs.gitlab.com/ee/user/project/deploy_tokens/#git-clone-a-repository). Токены развертывания могут управляться только Мейнтейнерами.

В Azure DevOps:

packages.yml

```yaml
packages:
  - git: "https://{{env_var('DBT_ENV_SECRET_PERSONAL_ACCESS_TOKEN')}}@dev.azure.com/dbt-labs/awesome_project/_git/awesome_repo" # git HTTPS URL
```

Подробнее о создании личного токена доступа читайте [здесь](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops\&tabs=preview-page#create-a-pat).

В Bitbucket:

packages.yml

```yaml
packages:
  - git: "https://{{env_var('DBT_USER_NAME')}}:{{env_var('DBT_ENV_SECRET_PERSONAL_ACCESS_TOKEN')}}@bitbucketserver.com/scm/awesome_project/awesome_repo.git" # для Bitbucket Server
```

Подробнее о создании личного токена доступа читайте [здесь](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html).

## Настройка подкаталога для упакованных проектов

В общем случае, dbt ожидает, что `dbt_project.yml` будет расположен как файл верхнего уровня в пакете. Если упакованный проект вместо этого вложен в подкаталог — возможно, в рамках гораздо большего монорепозитория — вы можете опционально указать путь к папке как `subdirectory`. dbt попытается выполнить [разреженную проверку](https://git-scm.com/docs/git-sparse-checkout) только файлов, расположенных в этом подкаталоге. Обратите внимание, что вы должны использовать недавнюю версию `git` (`>=2.26.0`).

packages.yml

```yaml
packages:
  - git: "https://github.com/dbt-labs/dbt-labs-experimental-features" # git URL
    subdirectory: "materialized-views" # имя подкаталога, содержащего `dbt_project.yml`
```

### Локальные пакеты

«Локальный» пакет — это dbt‑проект, доступный из вашей локальной файловой системы. Такие пакеты лучше всего подходят для случаев, когда у вас есть общий набор моделей и макросов, который вы хотите использовать в нескольких downstream‑проектах dbt (при этом каждый downstream‑проект всё равно имеет свои собственные уникальные модели, макросы и т.д.).

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

packages.yml

```yaml
packages:
  - local: relative/path/to/subdirectory
```

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

packages.yml

```yaml
packages:
  # не рекомендуется - поддержка этих шаблонов варьируется
  - local: /../../redshift   # относительный путь к родительскому каталогу
  - local: /opt/dbt/redshift # абсолютный путь на системе
```

Существуют несколько конкретных случаев использования, когда мы рекомендуем использовать "локальный" пакет:

1. **Монорепозиторий** — Когда у вас есть несколько проектов, каждый вложен в подкаталог, в рамках монорепозитория. "Локальные" пакеты позволяют объединять проекты для координированной разработки и развертывания.
2. **Тестирование изменений** — Чтобы протестировать изменения в одном проекте или пакете в контексте нисходящего проекта или пакета, который его использует. Временно переключив установку на "локальный" пакет, вы можете вносить изменения в первый и сразу тестировать их во втором для более быстрой итерации. Это похоже на [редактируемые установки](https://pip.pypa.io/en/stable/topics/local-project-installs/) в Python.
3. **Вложенный проект** — Когда у вас есть вложенный проект, который определяет фикстуры и тесты для проекта утилитарных макросов, как [интеграционные тесты в пакете `dbt-utils`](https://github.com/dbt-labs/dbt-utils/tree/main/integration_tests).

## Какие пакеты доступны?

Чтобы посмотреть библиотеку опубликованных пакетов dbt, загляните в [dbt package hub](https://hub.getdbt.com)!

## Совместимость пакетов с dbt v2

Чтобы определить, совместим ли пакет с dbt v2, посетите [каталог пакетов dbt](https://hub.getdbt.com/) и найдите значок совместимости с dbt v2 или проверьте [настройку `require-dbt-version`](https://docs.getdbt.tech/reference/project-configs/require-dbt-version.md#pin-to-a-range) пакета.

* Пакеты, у которых значение `require-dbt-version` равно `2.0.0` или задаёт диапазон, включающий эту версию, совместимы с dbt v2. Например, `require-dbt-version: ">=1.10.0,<3.0.0"`.

  Даже если в каталоге пакетов не указана совместимость пакета, он всё равно может работать с v2. Взаимодействуйте с сопровождающими пакетов, чтобы отслеживать обновления, и перед развёртыванием [тщательно тестируйте пакеты](https://docs.getdbt.com/guides/dbt-package-compat?step=5), совместимость которых явно не подтверждена.

* Сопровождающие пакетов, которые хотят обеспечить совместимость своих пакетов с v2, могут найти инструкции в [руководстве по обновлению пакетов для dbt v2](https://docs.getdbt.tech/guides/dbt-package-compat.md).

Особенности пакетов Fivetran:

* Пакеты Fivetran `source` и `transformation` объединены в один пакет.
* Если вы вручную установили пакеты источников, такие как `fivetran/github_source`, необходимо убедиться, что установлен пакет `fivetran/github`, и деактивировать модели преобразования.

#### Сообщения о совместимости пакетов

Расхождения между предупреждениями v2 и журналами `dbt-autofix`

Предупреждения dbt v2 и журналы `dbt-autofix` могут содержать разные сообщения о совместимости пакетов.

Если вы используете [`dbt-autofix`](https://github.com/dbt-labs/dbt-autofix) при переходе на v2 в Studio IDE или расширении dbt для VS Code, вы можете заметить расхождения между сообщениями о совместимости пакетов в `dbt-autofix` и предупреждениями v2.

Вот почему:

* Предупреждения dbt v2 выдаются на основе значения `require-dbt-version` пакета и того, включает ли `require-dbt-version` версию `2.0.0`.
* Некоторые пакеты уже совместимы с v2, хотя их сопровождающие еще не обновили `require-dbt-version`.
* `dbt-autofix` знает об этих совместимых пакетах и не будет пытаться обновить пакет, о совместимости которого ему уже известно.

Это означает, что даже если вы видите предупреждение v2 для пакета, который `dbt-autofix` определяет как совместимый, вам не нужно менять этот пакет.

Это временное расхождение в сообщениях: мы работаем над внедрением улучшенного механизма определения совместимости из `dbt-autofix` в предупреждения v2.

Вот пример предупреждения v2 в Studio IDE, которое сообщает, что пакет несовместим с v2, хотя `dbt-autofix` указывает, что он совместим:

```text
dbt1065: Package 'dbt_utils' requires dbt version [>=1.30,<2.0.0], but current version is 2.0.0. This package may not be compatible with your dbt version. dbt(1065) [Ln 1, Col 1]
```

(Версии dbt: v2.0 и новее)

## Поставка навыков агента в составе пакета

Пакет может предоставлять не только модели и макросы — он также может включать [навыки агента](https://docs.getdbt.tech/docs/dbt-ai/package-skills.md): многократно используемые инструкции, которые агент для работы с кодом читает из файла `SKILL.md`. Агент не знает, что ваши модели слоя staging используют префикс `stg_`, поэтому команды вынуждены копировать такие соглашения между репозиториями, где они со временем начинают различаться. Использование пакета делает навыки агента версионируемой зависимостью, как и всё остальное.

Добавьте в пакет каталог `skills`, и каждый проект, который устанавливает этот пакет, получит эти навыки при выполнении `dbt deps`, при условии что в устанавливающем проекте задан флаг `ai_provider`. Инструкции по настройке см. в разделе [Установка навыков агента из пакетов dbt](https://docs.getdbt.tech/docs/dbt-ai/package-skills.md).

## Расширенная настройка пакетов

### Обновление пакета

Когда вы изменяете версию или ревизию в файле `packages.yml`, пакет в вашем проекте dbt не обновляется автоматически. Чтобы обновить пакет, выполните `dbt deps`. Также может потребоваться выполнить [полное обновление](https://docs.getdbt.tech/reference/commands/run.md) моделей из этого пакета.

### Закрепление пакетов

Начиная с версии v1.7, выполнение [`dbt deps`](https://docs.getdbt.tech/reference/commands/deps.md) "закрепляет" каждый пакет, создавая или обновляя файл `package-lock.yml` в *корне проекта*, где записан `packages.yml`.

Запуск [`dbt deps`](https://docs.getdbt.tech/reference/commands/deps.md) «закрепляет» каждую зависимость, создавая или обновляя файл `package-lock.yml` в *project\_root*, где расположен `packages.yml`.

* Файл `package-lock.yml` содержит сведения обо всех установленных пакетах.
* Если при последующих запусках `dbt deps` файлы `dependencies.yml` или `packages.yml` не изменились, dbt устанавливает пакеты из `package-lock.yml`.

Начиная с версии v0.14.0, dbt предупредит вас, если вы установите пакет, используя синтаксис `git`, без указания ревизии (см. ниже).

dbt выдаст предупреждение, если вы устанавливаете пакет, используя синтаксис `git`, не указав ревизию (см. ниже).

### Настройка пакетов

Вы можете настраивать модели и seeds в пакете из файла `dbt_project.yml`, например:

dbt\_project.yml

```yml

vars:
  snowplow:
    'snowplow:timezone': 'America/New_York'
    'snowplow:page_ping_frequency': 10
    'snowplow:events': "{{ ref('sp_base_events') }}"
    'snowplow:context:web_page': "{{ ref('sp_base_web_page_context') }}"
    'snowplow:context:performance_timing': false
    'snowplow:context:useragent': false
    'snowplow:pass_through_columns': []

models:
  snowplow:
    +schema: snowplow

seeds:
  snowplow:
    +schema: snowplow_seeds
```

Например, при использовании пакета, специфичного для набора данных, вам может потребоваться настроить переменные для имен таблиц, содержащих ваши необработанные данные.

Конфигурации, заданные в YAML-файле вашего проекта (`dbt_project.yml`), будут переопределять любые конфигурации в пакете (как в YAML-файле проекта самого пакета, так и в блоках `config`).

### Указание незафиксированных Git-пакетов

Если в вашем проекте указан «незафиксированный» пакет Git, вы можете увидеть предупреждение вида:

```text
Git-пакет "https://github.com/dbt-labs/dbt-utils.git" не закреплен.
Это может привести к внесению изменений, нарушающих работу вашего проекта, без предупреждения!
```

Это предупреждение можно отключить, установив `warn-unpinned: false` в спецификации пакета. **Примечание:** Это не рекомендуется.

packages.yml

```yaml
packages:
  - git: https://github.com/dbt-labs/dbt-utils.git
    warn-unpinned: false
```

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

Если при работе с пакетами dbt возникают ошибки, см. ответы на частые вопросы:

Почему я получаю ошибку времени выполнения в моих пакетах?

Если в вашем файле packages.yml возникает приведённая ниже ошибка времени выполнения, это может быть связано с устаревшей версией пакета dbt\_utils, несовместимой с текущей версией dbt.

```shell
Running with dbt=xxx
Runtime Error
  Failed to read package: Runtime Error
    Invalid config version: 1, expected 2  
  Error encountered in dbt_utils/dbt_project.yml
```

Попробуйте обновить старую версию пакета dbt\_utils в вашем packages.yml до последней версии, доступной на [dbt hub](https://hub.getdbt.com/dbt-labs/dbt_utils/latest/):

```shell
packages:
- package: dbt-labs/dbt_utils

version: xxx
```

Если вы попробовали описанное выше решение и все еще сталкиваетесь с этой проблемой, свяжитесь с нашей службой поддержки по адресу <support@getdbt.com>, и мы будем рады помочь!

\[Ошибка] Не удалось найти пакет my\_project

Если имя пакета включено в `search_order` конфигурации `dispatch` на уровне проекта, dbt ожидает, что этот пакет будет содержать макросы, которые могут быть кандидатами для диспетчеризации. Если включенный пакет не содержит *никаких* макросов, dbt выдаст ошибку, подобную следующей:

```shell
Compilation Error
  In dispatch: Could not find package 'my_project'
```

Это не означает, что пакет или корневой проект отсутствует — это значит, что отсутствуют любые макросы из него, и поэтому он отсутствует в доступных для `dispatch` пространствах поиска.

Если вы попробовали шаг выше и все еще сталкиваетесь с этой проблемой, свяжитесь с нашей службой поддержки по адресу <support@getdbt.com>, и мы будем рады помочь!
