# Создание, тестирование, документирование и продвижение адаптеров

[Назад к гайдам](https://docs.getdbt.tech/guides.md)

[Menu ]()



important

dbt v1

Это руководство посвящено созданию адаптеров для dbt v1 на базе Python. О создании адаптеров для dbt v2 на базе Rust читайте в нашем [новом руководстве](https://docs.getdbt.tech/guides/adapter-creation-v2.md?step=1)

## Введение

Адаптеры — важнейший компонент dbt. На базовом уровне они обеспечивают подключение dbt к различным поддерживаемым платформам данных. На более высоком уровне адаптеры dbt v1 призваны помочь инженерам-аналитикам применять свои навыки на разных платформах, а также стандартизировать структуру аналитических проектов. Времена, когда при переходе на новую работу с другой платформой данных приходилось изучать новый язык или диалект SQL, остались в прошлом. В этом и заключается сила адаптеров в dbt v1.

Разобраться в особенностях разных баз данных и учесть их при разработке бывает непросто, но вы не одиноки. Если документации недостаточно, обратитесь за дополнительной помощью в канал Slack [#adapter-ecosystem](https://getdbt.slack.com/archives/C030A0UF5LM).

Навигация и разработка с учетом нюансов различных баз данных может быть сложной задачей, но вы не одиноки. Посетите канал Slack [#adapter-ecosystem](https://getdbt.slack.com/archives/C030A0UF5LM) для дополнительной помощи, выходящей за рамки документации.

### Все базы данных не одинаковы

Создание базы данных требует огромного количества работы. Вот список типичных слоев базы данных (от внешнего слоя к внутреннему):

* SQL API
* Клиентская библиотека / Драйвер
* Менеджер соединений сервера
* Парсер запросов
* Оптимизатор запросов
* Среда выполнения
* Слой доступа к хранилищу
* Хранилище

Там гораздо больше, чем просто SQL как язык. Базы данных (и хранилища данных) популярны, потому что они позволяют абстрагировать значительную часть сложности от вашего мозга к самой базе данных. Это позволяет вам сосредоточиться больше на данных.

dbt позволяет дальнейшую абстракцию и стандартизацию внешних слоев базы данных (SQL API, клиентская библиотека, менеджер соединений) в рамках, которые:

* Открывают технологии баз данных для менее технических пользователей (большая часть роли администратора баз данных была автоматизирована, аналогично тому, как большинство людей с веб-сайтами сегодня больше не должны быть "[веб-мастерами](https://en.wikipedia.org/wiki/Webmaster)").
* Позволяют более содержательные обсуждения о том, как должно осуществляться хранение данных.

Здесь адаптеры dbt становятся критически важными.

### Что нужно адаптировать?

Адаптеры dbt отвечают за *адаптацию* стандартной функциональности dbt к конкретной базе данных. Наши прототипические база данных и адаптер — PostgreSQL и dbt-postgres, и большинство наших адаптеров в некоторой степени основаны на функциональности, описанной в dbt-postgres.

Подключение dbt к новой базе данных потребует создания нового адаптера или расширения существующего адаптера.

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

### SQL API

Даже среди баз данных, совместимых с ANSI, существуют различия в грамматике SQL. Вот некоторые категории и примеры SQL-запросов, которые могут быть построены по-разному:

| Категория                                  | Область различий                                                                                                                             | Примеры                                                                                                                                                     |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Синтаксис операторов                       | Использование `IF EXISTS`                                                                                                                    | * `IF <TABLE> EXISTS, DROP TABLE`* `DROP <TABLE> IF EXISTS`                                                                                                 |
| Определение и семантика рабочих процессов  | Инкрементальные обновления                                                                                                                   | * `MERGE`* `DELETE; INSERT`                                                                                                                                 |
| Атрибуты/конфигурация отношений и столбцов | Конфигурации материализации, специфичные для базы данных                                                                                     | * `DIST = ROUND_ROBIN` (Synapse)* `DIST = EVEN` (Redshift)                                                                                                  |
| Разрешения                                 | Операторы предоставления, которые могут принимать только одного получателя за раз, по сравнению с теми, которые принимают списки получателей | * `grant SELECT on table dinner.corn to corn_kid, everyone`* `grant SELECT on table dinner.corn to corn_kid; grant SELECT on table dinner.corn to everyone` |

### Клиентская библиотека Python и менеджер соединений

Другая большая категория межбазовых различий связана с тем, как клиент подключается к базе данных и выполняет запросы к соединению. Чтобы интегрироваться с dbt, платформа данных должна иметь предварительно существующую клиентскую библиотеку Python или поддерживать ODBC, используя универсальную библиотеку Python, такую как pyodbc.

| Категория                       | Область различий                          | Примеры                                                                                                                                                     |
| ------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Учетные данные и аутентификация | Аутентификация                            | * Имя пользователя и пароль* MFA с `boto3` или токен Okta                                                                                                   |
| Открытие/закрытие соединения    | Создание нового соединения с базой данных | * `psycopg2.connect(connection_string)`* `google.cloud.bigquery.Client(...)`                                                                                |
| Вставка локальных данных        | Загрузка файлов .`csv` в память Python    | * `google.cloud.bigquery.Client.load_table_from_file(...)` (BigQuery)* `INSERT ... INTO VALUES ...` подготовленный оператор (большинство других баз данных) |

### Как dbt инкапсулирует и абстрагирует эти различия

Различия между базами данных кодируются в отдельные области:

| Компоненты     | Путь к коду                                       | Функция                                                                                        |
| -------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Классы Python  | `adapters/<adapter_name>`                         | Конфигурация (см. \[Классы Python]\(#python classes)                                           |
| Макросы        | `include/<adapter_name>/macros/adapters/`         | SQL API и синтаксис операторов (например, как создать схему или получить информацию о таблице) |
| Материализации | `include/<adapter_name>/macros/materializations/` | Определения рабочих процессов для таблиц/представлений/снимков                                 |

#### Классы Python

Эти классы реализуют все методы, отвечающие за:

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

| Класс                    | Описание                                                                                                                                                                                                            |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AdapterClass             | Конвертация типов на высоком уровне и любые методы Python, специфичные для базы данных                                                                                                                              |
| AdapterCredentials       | Типизированный словарь возможных профилей и связанных методов                                                                                                                                                       |
| AdapterConnectionManager | Все методы, отвечающие за подключение к базе данных и выполнение запросов                                                                                                                                           |
| AdapterRelation          | Как должны отображаться, печататься и заключаться в кавычки имена отношений. Используют ли имена отношений все три части? `catalog.model_name` (двухчастное имя) или `database.schema.model_name` (трехчастное имя) |
| AdapterColumn            | Как должны отображаться имена и свойства, специфичные для базы данных                                                                                                                                               |

#### Макросы

Набор *макросов*, отвечающих за генерацию SQL, совместимого с целевой базой данных.

#### Материализации

Набор *materializations* и соответствующих вспомогательных макросов, определённых в dbt с использованием Jinja и SQL. Они задают для dbt правила того, каким образом файлы моделей должны сохраняться в базе данных.

### Архитектура адаптера

Ниже представлена диаграмма потока, иллюстрирующая, как команда `dbt run` работает с адаптером `dbt-postgres`. Она показывает взаимосвязь между `dbt-core`, `dbt-adapters` и отдельными адаптерами.

[![Диаграмма архитектуры адаптера](/img/adapter-guide/adapter-architecture-diagram.png?v=2 "Диаграмма архитектуры адаптера")](#)Диаграмма архитектуры адаптера

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

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

Чем больше вы можете ответить "Да" на приведенные ниже вопросы, тем легче будет разработка вашего адаптера (и пользовательский опыт). См. [New Adapter Information Sheet wiki](https://github.com/dbt-labs/dbt-core/wiki/New-Adapter-Information-Sheet) для еще более конкретных вопросов.

Чем на большее число приведённых ниже вопросов вы можете ответить «Да», тем проще будет разрабатывать ваш адаптер и пользоваться им. Ещё более конкретные вопросы можно найти в [вики «Информационный лист нового адаптера»](https://github.com/dbt-labs/dbt/wiki/New-Adapter-Information-Sheet).

* Разработчик (и любые менеджеры продуктов) в идеале должны иметь значительный опыт работы в качестве конечного пользователя dbt. Если нет, настоятельно рекомендуется пройти хотя бы курсы [dbt Fundamentals](https://learn.getdbt.com/courses/dbt-fundamentals) и [Advanced Materializations](https://learn.getdbt.com/courses/advanced-materializations).

### База данных

* Завершает ли база данных транзакции достаточно быстро для интерактивной разработки?
* Можете ли вы выполнять SQL-запросы к платформе данных?
* Существует ли концепция схем?
* Поддерживает ли платформа данных ANSI SQL или хотя бы его подмножество?

### Драйвер / Библиотека соединений

* Существует ли драйвер на основе Python для взаимодействия с базой данных, который соответствует db API 2.0 (например, Psycopg2 для Postgres, pyodbc для SQL Server)?

* Поддерживает ли он: подготовленные операторы, множественные операторы или авторизацию токена единого входа на платформу данных?

* Есть ли драйвер на Python для взаимодействия с базой данных, соответствующий спецификации DB API 2.0 (например, Psycopg2 для Postgres и pyodbc для SQL Server)?

* Поддерживает ли он подготовленные запросы, выполнение нескольких SQL-операторов или авторизацию на платформе данных с помощью токена единого входа (SSO)?

* Существует ли в вашей организации установленный процесс публикации программного обеспечения с открытым исходным кодом?

Проще всего создать адаптер для dbt, когда рассматриваемая data warehouse/платформа имеет:

* стандартный интерфейс ANSI-SQL (или как можно ближе к нему),
* зрелую библиотеку соединений/SDK, использующую ODBC или Python DB 2 API, и
* способ, позволяющий разработчикам быстро итеративно работать с быстрыми чтениями и записями

### Поддержка вашего нового адаптера

Когда ваш адаптер станет более популярным, и люди начнут его использовать, вы можете быстро стать поддерживающим все более популярного проекта с открытым исходным кодом. С этой новой ролью приходят некоторые неожиданные обязанности, которые включают не только поддержку кода, но и работу с сообществом пользователей и участников. Чтобы помочь людям понять, чего ожидать от вашего проекта, вы должны рано и часто сообщать о своих намерениях в документации адаптера или README. Ответьте на такие вопросы, как: является ли это экспериментальной работой, которую люди должны использовать на свой страх и риск? Или это код производственного уровня, который вы обязуетесь поддерживать в будущем?

#### Поддержание совместимости кода с dbt Core

#### Обеспечение совместимости кода с dbt v1

Адаптер совместим с dbt v1, если он корректно реализует интерфейс, определённый в [dbt-adapters](https://github.com/dbt-labs/dbt-adapters/), и протестирован с помощью [dbt-tests-adapters](https://github.com/dbt-labs/dbt-adapters/tree/main/dbt-tests-adapter). До версии 1.8 dbt этот интерфейс находился в `dbt-core`.

Патч-релизы `dbt-adapters` *не* будут включать изменения, нарушающие совместимость, или новые функции для кода, ориентированного на адаптеры.

#### Версионирование и выпуск вашего адаптера

dbt Labs настоятельно рекомендует вам принять следующий подход при версионировании и выпуске вашего плагина.

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

* Укажите совместимость с основной версией `dbt-adapters` и задавайте ограничение на дополнительную версию только при наличии конкретной причины.
* Не импортируйте и не используйте код из `dbt-core`.
* Старайтесь выпускать новую дополнительную версию плагина при добавлении существенных новых возможностей. Обычно поводом для этого становится добавление поддержки новых возможностей, выпущенных в `dbt-adapters`, или изменения в самой платформе данных.
* Пока ваш плагин находится на раннем этапе развития и вы активно дорабатываете его возможности, старайтесь сохранять обратную совместимость и уведомления об устаревании как минимум в течение одной дополнительной версии. По мере развития плагина старайтесь сохранять обратную совместимость и уведомления об устаревании до следующей основной версии (v2).
* Выпускайте версии с исправлениями для своих плагинов по мере необходимости. Эти выпуски должны содержать только исправления.

примечание

До версии 1.8 dbt мы рекомендовали, чтобы дополнительная версия вашего плагина совпадала с дополнительной версией `dbt-core` (например, 1.1.x).

## Создание нового адаптера

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

Как только адаптер проходит большинство функциональных тестов на предыдущем шаге "Тестирование нового адаптера", пожалуйста, сообщите сообществу, что он доступен для использования, добавив адаптер на страницу ["Поддерживаемые платформы данных"](https://docs.getdbt.tech/docs/supported-data-platforms.md), следуя шагам, указанным в "Документирование вашего адаптера".

Если у вас возникнут вопросы, не стесняйтесь задавать их в канале Slack [#adapter-ecosystem](https://getdbt.slack.com/archives/C030A0UF5LM). Сообщество очень полезно и, вероятно, уже сталкивалось с подобной проблемой, как у вас.

### Создание каркаса нового адаптера

Чтобы создать новый плагин адаптера с нуля, вы можете использовать [dbt-database-adapter-scaffold](https://github.com/dbt-labs/dbt-database-adapter-scaffold) для запуска интерактивной сессии, которая сгенерирует каркас, на основе которого вы сможете строить.

Пример использования:

```text
$ cookiecutter gh:dbt-labs/dbt-database-adapter-scaffold
```

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

Одним из самых важных выборов, которые вы сделаете во время генерации cookiecutter, будет поле `is_sql_adapter`, которое является булевым значением, используемым для правильного применения импортов для `SQLAdapter` или `BaseAdapter`. Знание того, какой из них вам нужен, требует более глубокого понимания выбранной вами базы данных, но несколько хороших руководств для выбора:

* Имеет ли ваша база данных полный SQL API? Может ли она выполнять задачи с использованием SQL, такие как создание схем, удаление схем, запрос `information_schema` для вызовов метаданных? Если да, то это, скорее всего, SQLAdapter, где вы устанавливаете `is_sql_adapter` в `True`.
* Большинство адаптеров попадают под SQL адаптеры, поэтому мы выбрали его в качестве значения по умолчанию `True`.
* Очень возможно создать полностью функциональный `BaseAdapter`. Это потребует немного больше работы, так как он не поставляется с некоторыми предопределенными методами, которые предоставляет класс `SQLAdapter`. См. `dbt-bigquery` как хорошее руководство.

### Детали реализации

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

| Файл                                              | Компонент                                                         | Цель                                                                                                                                                                                                                                   |
| ------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `./setup.py`                                      | функция `setup()`                                                 | метаданные адаптера (имя пакета, версия, автор, домашняя страница и другие сведения)                                                                                                                                                   |
| `myadapter/dbt/adapters/myadapter/__init__.py`    | `AdapterPlugin`                                                   | объединение всей приведённой ниже информации в плагин dbt                                                                                                                                                                              |
| `myadapter/dbt/adapters/myadapter/connections.py` | класс `MyAdapterCredentials`                                      | параметры подключения к базе данных и её настройки с использованием выбранного драйвера Python                                                                                                                                         |
| `myadapter/dbt/adapters/myadapter/connections.py` | класс `MyAdapterConnectionManager`                                | определение того, как dbt взаимодействует с базой данных, включая открытие и закрытие соединений, выполнение запросов и получение данных. По сути, это обёртка над API базы данных или драйвером.                                      |
| `myadapter/dbt/include/bigquery/`                 | проект dbt с переопределениями макросов в формате "myadapter\_\_" | здесь вносятся изменения относительно global\_project, учитывающие различия в синтаксисе SQL для стандартных операций с базой данных (например, «создать таблицу на основе запроса SELECT» и «получить все отношения в текущей схеме») |
| `myadapter/dbt/adapters/myadapter/impl.py`        | `MyAdapterConfig`                                                 | конфигурации на уровне базы данных и отношений и                                                                                                                                                                                       |
| `myadapter/dbt/adapters/myadapter/impl.py`        | `MyAdapterAdapter`                                                | изменение того, *как* dbt выполняет операции, такие как макросы, и реализация другой необходимой функциональности на Python                                                                                                            |
| `myadapter/dbt/adapters/myadapter/column.py`      | `MyAdapterColumn`                                                 | определение специфичных для базы данных характеристик столбцов, таких как сопоставления типов данных                                                                                                                                   |

### Редактирование `setup.py`

Отредактируйте файл `myadapter/setup.py` и заполните недостающую информацию.

Вы можете пропустить этот шаг, если передали аргументы для `email`, `url`, `author` и `dependencies` в скрипт шаблона cookiecutter. Если вы планируете иметь вложенные структуры папок макросов, вам может потребоваться добавить записи в `package_data`, чтобы ваши исходные файлы макросов были установлены.

### Редактирование менеджера соединений

Отредактируйте менеджер соединений в `myadapter/dbt/adapters/myadapter/connections.py`. Этот файл определен в разделах ниже.

#### Класс Credentials

Класс учетных данных определяет все учетные данные, специфичные для базы данных (например, `username` и `password`), которые потребуются пользователям в [профиле подключения](https://docs.getdbt.tech/docs/supported-data-platforms.md) для вашего нового адаптера. Каждый контракт учетных данных должен наследоваться от dbt.adapters.base.Credentials и быть реализован как dataclass Python.

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

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

connections.py

```python

from dataclasses import dataclass
from typing import Optional

from dbt.adapters.base import Credentials


@dataclass
class MyAdapterCredentials(Credentials):
    host: str
    port: int = 1337
    username: Optional[str] = None
    password: Optional[str] = None

    @property
    def type(self):
        return 'myadapter'

    @property
    def unique_field(self):
        """
        Хэшируется и включается в анонимную телеметрию для отслеживания использования адаптера.
        Выберите поле, которое может уникально идентифицировать одну команду/организацию, использующую этот адаптер
        """
        return self.host

    def _connection_keys(self):
        """
        Список ключей для отображения в выводе `dbt debug`.
        """
        return ('host', 'port', 'database', 'username')
```

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

* Обязательно реализуйте показанный выше метод `_connection_keys` класса Credentials. Этот метод возвращает ключи, которые должны отображаться в выводе команды `dbt debug`. Как правило, рекомендуется возвращать все аргументы, используемые для подключения к базе данных, кроме пароля (включая необязательные аргументы).
* Создайте файл `profile_template.yml`, чтобы новый пользователь мог настроить профиль подключения с помощью интерактивных запросов при выполнении [команды `dbt init`](https://docs.getdbt.tech/reference/commands/init.md). Более подробная информация приведена в следующих шагах.
* Также можно определить сопоставление `ALIASES` в классе Credentials, чтобы пользователи могли использовать другие названия параметров конфигурации вместо 'database' или 'schema'. Например, если все пользователи базы данных MyAdapter называют свои базы данных «коллекциями», можно сделать следующее:

connections.py

```python
@dataclass
class MyAdapterCredentials(Credentials):
    host: str
    port: int = 1337
    username: Optional[str] = None
    password: Optional[str] = None

    ALIASES = {
        'collection': 'database',
    }
```

Тогда пользователи могут использовать `collection` ИЛИ `database` в своих `profiles.yml`, `dbt_project.yml` или вызовах `config()` для установки базы данных.

#### Методы класса `ConnectionManager`

После настройки учетных данных вам нужно будет реализовать некоторые методы, ориентированные на соединение. Они перечислены в docstring SQLConnectionManager, но здесь также будет предоставлен обзор.

**Методы для реализации:**

* `open`
* `get_response`
* `cancel`
* `exception_handler`
* `standardize_grants_dict`

##### `open(cls, connection)`

`open()` — это метод класса, который получает объект соединения (который может находиться в любом состоянии, но будет иметь объект `Credentials` с атрибутами, которые вы определили выше) и переводит его в состояние 'open'.

Обычно это означает выполнение следующих действий:

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

* создайте дескриптор соединения, используя базовую библиотеку базы данных, используя учетные данные

  * при успехе:

    * установите connection.state в `'open'`
    * установите connection.handle в объект дескриптора
      * это то, что должно иметь метод `cursor()`, который возвращает курсор!

  * при ошибке:

    * установите connection.state в `'fail'`
    * установите connection.handle в `None`
    * вызовите `dbt.exceptions.FailedToConnectException` с ошибкой и любой другой соответствующей информацией

Например:

connections.py

```python
    @classmethod
    def open(cls, connection):
        if connection.state == 'open':
            logger.debug('Connection is already open, skipping open.')
            return connection

        credentials = connection.credentials

        try:
            handle = myadapter_library.connect(
                host=credentials.host,
                port=credentials.port,
                username=credentials.username,
                password=credentials.password,
                catalog=credentials.database
            )
            connection.state = 'open'
            connection.handle = handle
        return connection
```

##### `get_response(cls, cursor)`

`get_response` — это метод класса, который получает объект курсора и возвращает информацию, специфичную для адаптера, о последней выполненной команде. Возвращаемое значение должно быть объектом `AdapterResponse`, который включает такие элементы, как `code`, `rows_affected`, `bytes_processed` и сводное сообщение `_message` для логирования в stdout.

connections.py

```python
    @classmethod
    def get_response(cls, cursor) -> AdapterResponse:
        code = cursor.sqlstate or "OK"
        rows = cursor.rowcount
        status_message = f"{code} {rows}"
        return AdapterResponse(
            _message=status_message,
            code=code,
            rows_affected=rows
        )
```

##### `cancel(self, connection)`

`cancel` — это метод экземпляра, который получает объект соединения и пытается отменить выполняющиеся запросы. Его поведение зависит от базы данных. Некоторые базы данных не поддерживают отмену запросов: в таком случае в реализации метода можно просто использовать `pass`, а классы адаптеров должны реализовывать метод `is_cancelable`, возвращающий False — при нажатии ctrl+c запросы в соединениях могут продолжать выполняться. Этот метод необходимо реализовывать с осторожностью, поскольку затрагиваемое соединение, скорее всего, будет использоваться в другом потоке.

connections.py

```python
    def cancel(self, connection):
        tid = connection.handle.transaction_id()
        sql = 'select cancel_transaction({})'.format(tid)
        logger.debug("Cancelling query '{}' ({})".format(connection_name, pid))
        _, cursor = self.add_query(sql, 'master')
        res = cursor.fetchone()
        logger.debug("Canceled query '{}': {}".format(connection_name, res))
```

##### `exception_handler(self, sql, connection_name='master')`

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

Если вы используете (настоятельно рекомендуемый) декоратор `@contextmanager`, вам нужно только обернуть `yield` внутри блока `try`, как показано ниже:

connections.py

```python
    @contextmanager
    def exception_handler(self, sql: str):
        try:
            yield
        except myadapter_library.DatabaseError as exc:
            self.release(connection_name)

            logger.debug('myadapter error: {}'.format(str(e)))
            raise dbt.exceptions.DatabaseException(str(exc))
        except Exception as exc:
            logger.debug("Error running SQL: {}".format(sql))
            logger.debug("Rolling back transaction.")
            self.release(connection_name)
            raise dbt.exceptions.RuntimeException(str(exc))
```

##### `standardize_grants_dict(self, grants_table: agate.Table) -> dict`

`standardize_grants_dict` — это метод, который возвращает стандартизированный словарь разрешений dbt, соответствующий тому, как пользователи сейчас настраивают разрешения в dbt. Входные данные — это результат вызова `SHOW GRANTS ON {{model}}`, загруженный в таблицу agate.

Если требуется дополнительная обработка таблицы agate, содержащей результаты `SHOW GRANTS ON {{model}}`, которую сложно выполнить в SQL, её можно выполнить здесь. Например, SQL-запрос для получения прав доступа *должен* исключать все права, выданные текущему пользователю или роли (например, OWNERSHIP). Если это невозможно сделать в SQL, такую фильтрацию можно выполнить в этом методе.

impl.py

```python
    @available
    def standardize_grants_dict(self, grants_table: agate.Table) -> dict:
        """
        :param grants_table: Таблица agate, содержащая результат запроса
            SQL, возвращенного get_show_grant_sql
        :return: Стандартизированный словарь, соответствующий конфигурации `grants`
        :rtype: dict
        """
        grants_dict: Dict[str, List[str]] = {}
        for row in grants_table:
            grantee = row["grantee"]
            privilege = row["privilege_type"]
            if privilege in grants_dict.keys():
                grants_dict[privilege].append(grantee)
            else:
                grants_dict.update({privilege: [grantee]})
        return grants_dict
```

### Редактирование реализации адаптера

Отредактируйте менеджер соединений в `myadapter/dbt/adapters/myadapter/impl.py`

Очень мало требуется для реализации самого адаптера. В некоторых адаптерах вам не нужно будет переопределять ничего. В других случаях вам, вероятно, потребуется переопределить некоторые из методов класса `convert_*`, или переопределить метод класса `is_cancelable` в других, чтобы он возвращал `False`.

#### `datenow()`

Этот метод класса предоставляет каноническую функцию даты адаптера. Она не используется, но требуется — в любом случае на всех адаптерах.

impl.py

```python
    @classmethod
    def date_function(cls):
        return 'datenow()'
```

### Редактирование логики SQL

dbt реализует определённые SQL-операции с помощью макросов Jinja. Хотя для многих таких операций (например, `create_schema`, `drop_schema`, `create_table` и других) предусмотрены подходящие реализации по умолчанию, при разработке нового адаптера может потребоваться переопределить один или несколько макросов.

#### Обязательные макросы

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

* `alter_column_type` ([исходный код](https://github.com/dbt-labs/dbt/blob/f988f76fccc1878aaf8d8631c05be3e9104b3b9a/core/dbt/include/global_project/macros/adapters/columns.sql#L37-L55))
* `check_schema_exists` ([исходный код](https://github.com/dbt-labs/dbt/blob/f988f76fccc1878aaf8d8631c05be3e9104b3b9a/core/dbt/include/global_project/macros/adapters/metadata.sql#L43-L55))
* `create_schema` ([исходный код](https://github.com/dbt-labs/dbt/blob/f988f76fccc1878aaf8d8631c05be3e9104b3b9a/core/dbt/include/global_project/macros/adapters/schema.sql#L1-L9))
* `drop_relation` ([исходный код](https://github.com/dbt-labs/dbt/blob/f988f76fccc1878aaf8d8631c05be3e9104b3b9a/core/dbt/include/global_project/macros/adapters/relation.sql#L34-L42))
* `drop_schema` ([исходный код](https://github.com/dbt-labs/dbt/blob/f988f76fccc1878aaf8d8631c05be3e9104b3b9a/core/dbt/include/global_project/macros/adapters/schema.sql#L12-L20))
* `get_columns_in_relation` ([исходный код](https://github.com/dbt-labs/dbt/blob/f988f76fccc1878aaf8d8631c05be3e9104b3b9a/core/dbt/include/global_project/macros/adapters/columns.sql#L1-L8)) (обязательно)
* `list_relations_without_caching` ([исходный код](https://github.com/dbt-labs/dbt/blob/f988f76fccc1878aaf8d8631c05be3e9104b3b9a/core/dbt/include/global_project/macros/adapters/metadata.sql#L58-L65)) (обязательно)
* `list_schemas` ([исходный код](https://github.com/dbt-labs/dbt/blob/f988f76fccc1878aaf8d8631c05be3e9104b3b9a/core/dbt/include/global_project/macros/adapters/metadata.sql#L29-L40))
* `rename_relation` ([исходный код](https://github.com/dbt-labs/dbt/blob/f988f76fccc1878aaf8d8631c05be3e9104b3b9a/core/dbt/include/global_project/macros/adapters/relation.sql#L56-L65))
* `truncate_relation` ([исходный код](https://github.com/dbt-labs/dbt/blob/f988f76fccc1878aaf8d8631c05be3e9104b3b9a/core/dbt/include/global_project/macros/adapters/relation.sql#L45-L53))
* `current_timestamp` ([исходный код](https://github.com/dbt-labs/dbt/blob/f988f76fccc1878aaf8d8631c05be3e9104b3b9a/core/dbt/include/global_project/macros/adapters/freshness.sql#L1-L8)) (обязательно)
* `copy_grants`

#### Диспетчеризация адаптера

Большинство современных баз данных поддерживают большую часть стандартной спецификации SQL. Однако существуют базы данных, которые *не поддерживают* критические аспекты спецификации SQL, или они предоставляют свои собственные нестандартные механизмы для реализации той же функциональности. Чтобы учесть эти вариации в поддержке SQL, dbt предоставляет механизм, называемый [множественной диспетчеризацией](https://en.wikipedia.org/wiki/Multiple_dispatch) для макросов. С помощью этой функции макросы могут быть переопределены для конкретных адаптеров. Это позволяет реализовать высокоуровневые методы (например, "создать таблица") специфическим для базы данных способом.

adapters.sql

```jinja2

{# dbt вызовет этот макрос по имени, предоставив любые аргументы #}
{% macro create_table_as(temporary, relation, sql) -%}

  {# dbt направит вызов макроса к соответствующему макросу #}
  {{ return(
      adapter.dispatch('create_table_as')(temporary, relation, sql)
     ) }}
{%- endmacro %}



{# Если ни один макрос не соответствует указанному адаптеру, будет использован "default" #}
{% macro default__create_table_as(temporary, relation, sql) -%}
   ...
{%- endmacro %}



{# Пример, который определяет специальную логику для Redshift #}
{% macro redshift__create_table_as(temporary, relation, sql) -%}
   ...
{%- endmacro %}



{# Пример, который определяет специальную логику для BigQuery #}
{% macro bigquery__create_table_as(temporary, relation, sql) -%}
   ...
{%- endmacro %}
```

Макрос `adapter.dispatch()` принимает второй аргумент, `packages`, который представляет собой набор "пространств имен поиска", в которых можно найти потенциальные реализации диспетчеризуемого макроса. Это позволяет пользователям адаптеров, поддерживаемых сообществом, расширять или "подменять" диспетчеризуемые макросы из общих пакетов, таких как `dbt-utils`, с адаптер-специфическими версиями в их собственном проекте или других установленных пакетах. См.:

* Примеры "подменяющих" пакетов: [`spark-utils`](https://github.com/dbt-labs/spark-utils), [`tsql-utils`](https://github.com/dbt-msft/tsql-utils)
* [документация `adapter.dispatch`](https://docs.getdbt.tech/reference/dbt-jinja-functions/dispatch.md)

#### Переопределение методов адаптера

Хотя большая часть функциональности, специфичной для адаптера dbt, может быть изменена в макросах адаптера, также может иметь смысл переопределить методы адаптера напрямую. В этом примере предположим, что база данных не поддерживает параметр `cascade` для `drop schema`. Вместо этого мы можем реализовать приближение, где мы удаляем каждое отношение, а затем удаляем схему.

impl.py

```python
    def drop_schema(self, relation: BaseRelation):
        relations = self.list_relations(
            database=relation.database,
            schema=relation.schema
        )
        for relation in relations:
            self.drop_relation(relation)
        super().drop_schema(relation)
```

#### Макросы разрешений

Информацию о макросах, необходимых для операторов `GRANT`, см. в [этом обсуждении на GitHub](https://github.com/dbt-labs/dbt/discussions/5468):

### Флаги изменения поведения

Начиная с версий `dbt-adapters==1.5.0` и `dbt-core==1.8.7`, разработчики адаптеров могут реализовывать собственные флаги изменения поведения. Подробнее см. в разделе [Behavior changes](https://docs.getdbt.tech/reference/global-configs/behavior-changes.md).

Флаги изменения поведения не предназначены для долгосрочных флагов функций. Они должны быть реализованы с ожиданием, что поведение станет стандартным в течение ожидаемого периода времени. Чтобы реализовать флаг изменения поведения, вы должны предоставить имя для флага, настройку по умолчанию (`True` / `False`), необязательный источник и описание и/или ссылку на документацию флага на docs.getdbt.com.

Мы рекомендуем иметь описание и ссылку на документацию, когда это возможно. Описание и/или документация должны предоставить конечным пользователям контекст, почему существует флаг, почему они могут видеть предупреждение и почему они могут захотеть использовать флаг изменения поведения. Флаги изменения поведения могут быть реализованы путем переопределения `_behavior_flags()` на адаптере в `impl.py`:

impl.py

```python
class ABCAdapter(BaseAdapter):
    ...
    @property
    def _behavior_flags(self) -> List[BehaviorFlag]:
        return [
            {
                "name": "enable_new_functionality_requiring_higher_permissions",
                "default": False,
                "source": "dbt-abc",
                "description": (
                    "Адаптер dbt-abc реализует новый метод получения метаданных. "
                    "Это более производительный способ получения метаданных dbt, но требует более высоких разрешений на платформе. "
                    "Включение этого без предоставления необходимых разрешений приведет к ошибке. "
                    "Ожидается, что эта функция станет обязательной к весне 2025 года."
                ),
                "docs_url": "https://docs.getdbt.tech/reference/global-configs/behavior-changes#abc-enable_new_functionality_requiring_higher_permissions",
            }
        ]
```

После того, как флаг изменения поведения был реализован, его можно использовать на адаптере как в `impl.py`, так и в макросах Jinja:

impl.py

```python
class ABCAdapter(BaseAdapter):
    ...
    def some_method(self, *args, **kwargs):
        if self.behavior.enable_new_functionality_requiring_higher_permissions:
            # делаем новое
        else:
            # делаем старое
```

adapters.sql

```sql
{% macro some_macro(**kwargs) %}
    {% if adapter.behavior.enable_new_functionality_requiring_higher_permissions %}
        {# делаем новое #}
    {% else %}
        {# делаем старое #}
    {% endif %}
{% endmacro %}
```

Каждый раз, когда флаг поведения оценивается как `False`, он предупреждает пользователя, информируя его о том, что в будущем произойдет изменение.

Это предупреждение не отображается, когда флаг оценивается как `True`, так как пользователь уже находится в новом опыте.

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

impl.py

```python
    class ABCAdapter(BaseAdapter):
        ...
        def some_method(self, *args, **kwargs):
            if self.behavior.enable_new_functionality_requiring_higher_permissions.no_warn:
                # делаем новое
            else:
                # делаем старое
```

adapters.sql

```sql
{% macro some_macro(**kwargs) %}
    {% if adapter.behavior.enable_new_functionality_requiring_higher_permissions.no_warn %}
        {# делаем новое #}
    {% else %}
        {# делаем старое #}
    {% endif %}
{% endmacro %}
```

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

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

### Другие файлы

#### `profile_template.yml`

Чтобы команда [`dbt init`](https://docs.getdbt.tech/reference/commands/init.md) могла предложить пользователям при настройке нового проекта и профиля соединения, вы должны включить **шаблон профиля**. Путь к файлу должен быть `dbt/include/<adapter_name>/profile_template.yml`. Возможно предоставить подсказки, значения по умолчанию и условные подсказки на основе методов соединения, которые требуют различных поддерживающих атрибутов. Пользователи также смогут включать пользовательские версии этого файла в свои собственные проекты, с фиксированными значениями, специфичными для их организации, чтобы поддерживать своих коллег при первом использовании вашего адаптера dbt.

См. примеры:

* [dbt-postgres](https://github.com/dbt-labs/dbt-postgres/blob/main/dbt/include/postgres/profile_template.yml)
* [dbt-redshift](https://github.com/dbt-labs/dbt-redshift/blob/main/dbt/include/redshift/profile_template.yml)
* [dbt-snowflake](https://github.com/dbt-labs/dbt-snowflake/blob/main/dbt/include/snowflake/profile_template.yml)
* [dbt-bigquery](https://github.com/dbt-labs/dbt-bigquery/blob/main/dbt/include/bigquery/profile_template.yml)

#### `__version__.py`

Чтобы команда `dbt --version` показывала последнюю версию v1, поддерживаемую адаптером, обязательно добавьте файл `__version__.py`. Путь к файлу: `dbt/adapters/<adapter_name>/__version__.py`. Мы рекомендуем использовать последнюю версию v1. По мере добавления в адаптер поддержки более поздних версий этот файл необходимо обновлять. Образец файла можно найти в этом [примере](https://github.com/dbt-labs/dbt-snowflake/blob/main/dbt/adapters/snowflake/__version__.py).

Следует отметить, что оба этих файла включены в сгенерированный вывод `dbt-database-adapter-scaffold`, поэтому при использовании каркаса эти файлы будут включены.

## Тестирование вашего адаптера

Этот документ имеет два раздела:

1. Обратитесь к "О тестовой структуре" для описания стандартной структуры, которую мы поддерживаем для использования pytest вместе с dbt. Он включает пример, который показывает анатомию простого тестового случая.
2. Обратитесь к "Тестирование вашего адаптера" для пошагового руководства по использованию нашего готового набора "базовых" тестов, которые проверят, что ваш адаптер соответствует базовому функционалу dbt.

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

* Ваш адаптер должен быть совместим с dbt **v1.1** или более новой версией
* Вы должны быть знакомы с **pytest**: <https://docs.pytest.org>

### О тестовой структуре

[dbt-adapters-tests](https://github.com/dbt-labs/dbt-adapters/tree/main/dbt-tests-adapter) предлагает стандартную структуру для запуска предопределенных функциональных тестов и для определения ваших собственных тестов. Основная тестовая структура построена с использованием `pytest`, зрелой и стандартной библиотеки для тестирования проектов на Python.

Она включает базовые утилиты для настройки pytest + dbt. Эти утилиты используются всеми "предопределенными" функциональными тестами и позволяют быстро писать свои собственные тесты.

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

1. **Быстро настройте «проект» dbt.** Определите ресурсы проекта с помощью таких методов, как `models()` и `seeds()`. Используйте `project_config_update()`, чтобы передать настройки в `dbt_project.yml`.
2. **Определите последовательность команд dbt.** Самая важная вспомогательная функция — `run_dbt()`, которая возвращает [результаты](https://docs.getdbt.tech/reference/dbt-classes.md#result-objects) каждой команды dbt. Она принимает список аргументов CLI (подкоманда + флаги), а также необязательный второй аргумент `expect_pass=False` для случаев, когда вы ожидаете, что команда завершится с ошибкой.
3. **Проверьте результаты выполнения этих команд dbt.** Например, `check_relations_equal()` проверяет, что два объекта базы данных имеют одинаковую структуру и содержимое. Вы также можете написать собственные проверки с помощью `assert`, анализируя результаты команды dbt или запрашивая произвольные объекты базы данных с помощью `project.run_sql()`.

Полный набор вспомогательных функций с аргументами и аннотациями можно найти в [`util.py`](https://github.com/dbt-labs/dbt/blob/1.latest/core/dbt/tests/util.py). Вы также встретите их в различных тестовых сценариях. Хотя все вспомогательные функции предназначены для повторного использования, не все из них понадобятся в каждом тесте. В примере ниже мы покажем простой тестовый сценарий, в котором используется лишь несколько вспомогательных функций.

#### Пример: простой тестовый случай

Этот пример покажет вам анатомию тестового случая с использованием dbt + pytest. Мы создадим повторно используемые компоненты, объединим их, чтобы сформировать "проект" dbt, и определим последовательность команд dbt. Затем мы используем утверждения Python `assert`, чтобы убедиться, что эти команды выполняются успешно (или неудачно), как мы ожидаем.

В разделе ["Начало работы с запуском базовых тестов"](#getting-started-running-basic-tests) мы предложим пошаговые инструкции по установке и настройке `pytest`, чтобы вы могли запустить его на своей машине. Пока что важнее увидеть, как части тестового случая сочетаются друг с другом.

Этот пример включает seed, модель и два теста — один из которых завершится неудачей.

1. Определите строки Python, которые будут представлять содержимое файлов в вашем проекте dbt. Определение их в отдельном файле позволяет повторно использовать одни и те же компоненты в разных тестовых случаях. Имя pytest для этого типа повторно используемого компонента — "fixture".

tests/functional/example/fixtures.py

```python
# seeds/my_seed.csv
my_seed_csv = """
id,name,some_date
1,Easton,1981-05-20T06:46:51
2,Lillian,1978-09-03T18:10:33
3,Jeremiah,1982-03-11T03:59:51
4,Nolan,1976-05-06T20:21:35
""".lstrip()

# models/my_model.sql
my_model_sql = """
select * from {{ ref('my_seed') }}
union all
select null as id, null as name, null as some_date
"""

# models/my_model.yml
my_model_yml = """
version: 2
models:
  - name: my_model
    columns:
      - name: id
        data_tests:
          - unique
          - not_null  # этот тест завершится неудачей
"""
```

2. Используйте "fixtures", чтобы определить проект для вашего тестового случая. Эти fixtures всегда имеют область действия **class**, где класс представляет один тестовый случай — то есть один проект dbt или сценарий. (Один и тот же тестовый случай может использоваться для одного или нескольких фактических тестов, которые мы увидим на шаге 3.) Следуя стандартным конфигурациям pytest, имя файла должно начинаться с `test_`, а имя класса должно начинаться с `Test`.

tests/functional/example/test\_example\_failing\_test.py

```python
import pytest
from dbt.tests.util import run_dbt

# наше содержимое файлов
from tests.functional.example.fixtures import (
    my_seed_csv,
    my_model_sql,
    my_model_yml,
)

# класс должен начинаться с 'Test'
class TestExample:
    """
    Методы в этом классе будут двух типов:
    1. Fixtures, определяющие "проект" dbt для этого тестового случая.
       Они имеют область действия класса и повторно используются для всех тестов в классе.
    2. Фактические тесты, имена которых начинаются с 'test_'.
       Они определяют последовательности команд dbt и утверждения 'assert'.
    """
    
    # конфигурация в dbt_project.yml
    @pytest.fixture(scope="class")
    def project_config_update(self):
        return {
          "name": "example",
          "models": {"+materialized": "view"}
        }

    # все, что идет в директорию "seeds"
    @pytest.fixture(scope="class")
    def seeds(self):
        return {
            "my_seed.csv": my_seed_csv,
        }

    # все, что идет в директорию "models"
    @pytest.fixture(scope="class")
    def models(self):
        return {
            "my_model.sql": my_model_sql,
            "my_model.yml": my_model_yml,
        }
        
    # продолжается ниже
```

3. Теперь, когда мы настроили наш проект, пришло время определить последовательность команд dbt и утверждений. Мы определяем один или несколько методов в том же файле, в том же классе (`TestExampleFailingTest`), имена которых начинаются с `test_`. Эти методы используют ту же настройку (сценарий проекта), что и выше, но они могут выполняться независимо pytest — поэтому они не должны зависеть друг от друга.

tests/functional/example/test\_example\_failing\_test.py

```python
    # продолжение выше

    # Фактическая последовательность команд dbt и утверждений
    # pytest позаботится обо всех "setup" + "teardown"
    def test_run_seed_test(self, project):
        """
        Seed, затем run, затем test. Мы ожидаем, что один из тестов завершится неудачей
        Альтернативный паттерн — использовать pytest "xfail" (см. ниже)
        """
        # seed seeds
        results = run_dbt(["seed"])
        assert len(results) == 1
        # run models
        results = run_dbt(["run"])
        assert len(results) == 1
        # test tests
        results = run_dbt(["test"], expect_pass = False) # ожидаем неудачный тест
        assert len(results) == 2
        # проверяем, что результаты включают один успешный и один неудачный тест
        result_statuses = sorted(r.status for r in results)
        assert result_statuses == ["fail", "pass"]

    @pytest.mark.xfail
    def test_build(self, project):
        """Ожидаем неудачный тест"""
        # делаем все
        results = run_dbt(["build"])
```

3. Наш тест готов к запуску! Последний шаг — вызвать `pytest` из командной строки. Мы пройдем через фактическую настройку и конфигурацию `pytest` в следующем разделе.

terminal

```sh
$ python3 -m pytest tests/functional/test_example.py
=========================== test session starts ============================
platform ... -- Python ..., pytest-..., pluggy-...
rootdir: ...
plugins: ...

tests/functional/test_example.py .X                                  [100%]

======================= 1 passed, 1 xpassed in 1.38s =======================
```

Вы можете найти больше способов запуска тестов, а также полную справку по командам в [документации по использованию pytest](https://docs.pytest.org/how-to/usage.html).

Флаг `-s` (или `--capture=no`) удобен для вывода логов выполняемых вызовов dbt, а также для перехода в интерактивный отладчик, если вы его добавили. Вы также можете использовать переменные окружения для задания [глобальных настроек dbt](https://docs.getdbt.tech/reference/global-configs/about-global-configs.md), например (Версии dbt: v1.11 и новее) `DBT_ENGINE_DEBUG` (для вывода логов уровня debug).

### Тестирование этого адаптера

Любой, кто установил `dbt-core` и желает определить свои собственные тестовые случаи, может использовать структуру, представленную в первом разделе. Эта структура особенно полезна для тестирования стандартного поведения dbt на разных базах данных.

С этой целью мы создали и сделали доступным [пакет повторно используемых тестовых случаев адаптера](https://github.com/dbt-labs/dbt-adapters/tree/main/dbt-tests-adapter) для создателей и поддерживающих плагинов адаптеров. Эти тестовые случаи охватывают базовую ожидаемую функциональность, а также функциональность, которая часто требует различных реализаций на разных базах данных.

В настоящее время этот пакет также находится в репозитории `dbt-labs/dbt`, но отдельно от Python-пакета `dbt-core`.

### Категории тестов

В процессе создания и поддержки вашего адаптера, вероятно, вы реализуете тесты, которые попадают в три широкие категории:

1. **Базовые тесты**, которые ожидается, что каждый плагин адаптера пройдет. Они определены в `tests.adapter.basic`. Учитывая различия между платформами данных, они могут потребовать небольших изменений или повторной реализации. Значительное переопределение или отключение этих тестов должно быть с веской причиной, так как каждый из них представляет собой базовую функциональность, ожидаемую пользователями dbt. Например, если ваш адаптер не поддерживает инкрементальные модели, вы должны отключить тест, [пометив его как `skip` или `xfail`](https://docs.pytest.org/en/latest/how-to/skipping.html), а также отметить это ограничение в любой документации, README и руководствах по использованию, которые сопровождают ваш адаптер.

2. **Опциональные тесты**, для второстепенной функциональности, которая является общей для плагинов, но не обязательной для базового использования. Ваш плагин может выбрать эти тестовые случаи, унаследовав существующие или повторно реализовав их с изменениями. На данный момент эта категория включает все тесты, расположенные за пределами подкаталога `basic`. Больше тестов будет добавлено по мере того, как мы конвертируем старые тесты, определенные на dbt-core, и зрелые плагины для использования стандартной структуры.

3. **Пользовательские тесты** для проверки поведения, специфичного для вашего адаптера / платформы данных. У каждого data warehouse есть свои особенности и нюансы. Мы рекомендуем использовать тот же фреймворк на основе `pytest`, утилиты и фикстуры для написания собственных тестов функциональности, уникальной для вашего адаптера.

Если вы столкнулись с проблемой в основном фреймворке или в базовых/необязательных тестовых сценариях — либо написали пользовательский тест, который, по вашему мнению, был бы актуален и полезен другим разработчикам плагинов-адаптеров, — создайте issue или PR в репозитории `dbt-labs/dbt` на GitHub.

### Начало работы с запуском базовых тестов

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

1. Установите зависимости
2. Настройте и сконфигурируйте pytest
3. Определите тестовые случаи

### Установите зависимости

У вас уже должна быть виртуальная среда с установленными `dbt-core` и вашим плагином адаптера. Вам также нужно будет установить:

* [`pytest`](https://pypi.org/project/pytest/)
* [`dbt-tests-adapter`](https://pypi.org/project/dbt-tests-adapter/), набор общих тестовых случаев
* (опционально) [`pytest` плагины](https://docs.pytest.org/en/7.0.x/reference/plugin_list.html) — мы будем использовать `pytest-dotenv` ниже

Или укажите все зависимости в файле требований, например:

dev\_requirements.txt

```txt
pytest
pytest-dotenv
dbt-tests-adapter
```

```sh
python -m pip install -r dev_requirements.txt
```

### Настройте и сконфигурируйте pytest

Сначала настройте себя для запуска `pytest`, создав файл с именем `pytest.ini` в корне вашего репозитория:

pytest.ini

```python
[pytest]
filterwarnings =
    ignore:.*'soft_unicode' has been renamed to 'soft_str'*:DeprecationWarning
    ignore:unclosed file .*:ResourceWarning
env_files =
    test.env  # использует плагин pytest-dotenv
              # это позволяет вам хранить переменные окружения для подключения к базе данных в файле с именем test.env
              # вместо передачи их в каждой команде CLI или установки в `PYTEST_ADDOPTS`
              # обязательно добавьте "test.env" в .gitignore!
testpaths =
    tests/functional  # имя по соглашению
```

Затем создайте файл конфигурации в вашем каталоге тестов. В нем вы захотите определить всю необходимую конфигурацию профиля для подключения к вашей платформе данных в локальной разработке и непрерывной интеграции. Мы рекомендуем устанавливать эти значения с помощью переменных окружения, так как этот файл будет проверен в систему контроля версий.

tests/conftest.py

```python
import pytest
import os

# Импортируйте стандартные функциональные fixtures как плагин
# Примечание: fixtures с областью действия session должны быть локальными
pytest_plugins = ["dbt.tests.fixtures.project"]

# Словарь профиля, используемый для записи profiles.yml
# dbt предоставит уникальную схему для каждого теста, поэтому мы не указываем 'schema' здесь
@pytest.fixture(scope="class")
def dbt_profile_target():
    return {
        'type': '<myadapter>',
        'threads': 1,
        'host': os.getenv('HOST_ENV_VAR_NAME'),
        'user': os.getenv('USER_ENV_VAR_NAME'),
        ...
    }
```

### Определите тестовые случаи

Как в приведенном выше примере, каждый тестовый случай определяется как класс и имеет свою собственную настройку "проекта". Чтобы начать, вы можете импортировать все базовые тестовые случаи и попробовать запустить их без изменений.

tests/functional/adapter/test\_basic.py

```python
import pytest

from dbt.tests.adapter.basic.test_base import BaseSimpleMaterializations
from dbt.tests.adapter.basic.test_singular_tests import BaseSingularTests
from dbt.tests.adapter.basic.test_singular_tests_ephemeral import BaseSingularTestsEphemeral
from dbt.tests.adapter.basic.test_empty import BaseEmpty
from dbt.tests.adapter.basic.test_ephemeral import BaseEphemeral
from dbt.tests.adapter.basic.test_incremental import BaseIncremental
from dbt.tests.adapter.basic.test_generic_tests import BaseGenericTests
from dbt.tests.adapter.basic.test_snapshot_check_cols import BaseSnapshotCheckCols
from dbt.tests.adapter.basic.test_snapshot_timestamp import BaseSnapshotTimestamp
from dbt.tests.adapter.basic.test_adapter_methods import BaseAdapterMethod

class TestSimpleMaterializationsMyAdapter(BaseSimpleMaterializations):
    pass


class TestSingularTestsMyAdapter(BaseSingularTests):
    pass


class TestSingularTestsEphemeralMyAdapter(BaseSingularTestsEphemeral):
    pass


class TestEmptyMyAdapter(BaseEmpty):
    pass


class TestEphemeralMyAdapter(BaseEphemeral):
    pass


class TestIncrementalMyAdapter(BaseIncremental):
    pass


class TestGenericTestsMyAdapter(BaseGenericTests):
    pass


class TestSnapshotCheckColsMyAdapter(BaseSnapshotCheckCols):
    pass


class TestSnapshotTimestampMyAdapter(BaseSnapshotTimestamp):
    pass


class TestBaseAdapterMethod(BaseAdapterMethod):
    pass
```

Наконец, запустите pytest:

```sh
python3 -m pytest tests/functional
```

### Изменение тестовых случаев

Вам может потребоваться внести небольшие изменения в конкретный тестовый случай, чтобы он прошел на вашем адаптере. Механизм для этого прост: вместо простого наследования "базового" теста с `pass`, вы можете переопределить любой из его fixtures или тестовых методов.

Например, на Redshift нам нужно явно привести столбец в входном seed к типу данных `varchar(64)`:

tests/functional/adapter/test\_basic.py

```python
import pytest
from dbt.tests.adapter.basic.files import seeds_base_csv, seeds_added_csv, seeds_newcolumns_csv
from dbt.tests.adapter.basic.test_snapshot_check_cols import BaseSnapshotCheckCols

# установите тип данных столбца name в seed 'added', чтобы он
# мог содержать '_update', который добавляется
schema_seed_added_yml = """
version: 2
seeds:
  - name: added
    config:
      column_types:
        name: varchar(64)
"""

class TestSnapshotCheckColsRedshift(BaseSnapshotCheckCols):
    # Redshift определяет столбец 'name' таким образом, что он недостаточно велик
    # чтобы содержать '_update', добавленный в тесте.
    @pytest.fixture(scope="class")
    def models(self):
        return {
            "base.csv": seeds_base_csv,
            "added.csv": seeds_added_csv,
            "seeds.yml": schema_seed_added_yml,
        }
```

В качестве другого примера, адаптер `dbt-bigquery` просит пользователей "авторизовать" замену таблица на представление, предоставив флаг `--full-refresh`. Причина: в логике материализации таблицы представление с тем же именем должно быть сначала удалено; если запрос таблицы завершится неудачей, модель будет отсутствовать.

Зная эту возможность, "базовый" тестовый случай предлагает переключатель `require_full_refresh` на fixture класса `test_config`. Для BigQuery мы его включим:

tests/functional/adapter/test\_basic.py

```python
import pytest
from dbt.tests.adapter.basic.test_base import BaseSimpleMaterializations

class TestSimpleMaterializationsBigQuery(BaseSimpleMaterializations):
    @pytest.fixture(scope="class")
    def test_config(self):
        # эффект: добавление флага '--full-refresh' в необходимый шаг 'dbt run'
        return {"require_full_refresh": True}
```

Всегда стоит задаться вопросом, представляют ли требуемые изменения пробелы в воспринимаемой или ожидаемой функциональности dbt. Являются ли это простыми деталями реализации, которые любой пользователь этой базы данных поймет? Являются ли они ограничениями, которые стоит задокументировать?

Если же они отражают неверные предположения в «базовых» тестовых сценариях, которые не учитывают распространённый подход, используемый в других типах баз данных, — пожалуйста, создайте issue или PR в репозитории `dbt-labs/dbt` на GitHub.

### Запуск с несколькими профилями

Некоторые базы данных поддерживают несколько методов подключения, которые соответствуют фактически различной функциональности за кулисами. Например, адаптер `dbt-spark` поддерживает подключения к кластерам Apache Spark *и* средам выполнения Databricks, которые поддерживают дополнительную функциональность из коробки, включенную форматом файлов Delta.

tests/conftest.py

```python
def pytest_addoption(parser):
    parser.addoption("--profile", action="store", default="apache_spark", type=str)


# Использование @pytest.mark.skip_profile('apache_spark') использует 'skip_by_profile_type'
# autouse fixture ниже
def pytest_configure(config):
    config.addinivalue_line(
        "markers",
        "skip_profile(profile): пропустить тест для данного профиля",
    )

@pytest.fixture(scope="session")
def dbt_profile_target(request):
    profile_type = request.config.getoption("--profile")
    elif profile_type == "databricks_sql_endpoint":
        target = databricks_sql_endpoint_target()
    elif profile_type == "apache_spark":
        target = apache_spark_target()
    else:
        raise ValueError(f"Неверный тип профиля '{profile_type}'")
    return target

def apache_spark_target():
    return {
        "type": "spark",
        "host": "localhost",
        ...
    }

def databricks_sql_endpoint_target():
    return {
        "type": "spark",
        "host": os.getenv("DBT_DATABRICKS_HOST_NAME"),
        ...
    }

@pytest.fixture(autouse=True)
def skip_by_profile_type(request):
    profile_type = request.config.getoption("--profile")
    if request.node.get_closest_marker("skip_profile"):
        for skip_profile_type in request.node.get_closest_marker("skip_profile").args:
            if skip_profile_type == profile_type:
                pytest.skip("пропущено на профиле '{profile_type}'")
```

Если есть тесты, которые *не должны* выполняться для данного профиля:

tests/functional/adapter/basic.py

```python
# Снимки требуют доступа к формату файлов Delta, доступному на нашем подключении Databricks,
# поэтому давайте пропустим на Apache Spark
@pytest.mark.skip_profile('apache_spark')
class TestSnapshotCheckColsSpark(BaseSnapshotCheckCols):
    @pytest.fixture(scope="class")
    def project_config_update(self):
        return {
            "seeds": {
                "+file_format": "delta",
            },
            "snapshots": {
                "+file_format": "delta",
            }
        }
```

Наконец:

```sh
python3 -m pytest tests/functional --profile apache_spark
python3 -m pytest tests/functional --profile databricks_sql_endpoint
```

## Документирование нового адаптера

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

### Доступность вашего адаптера

Многие члены сообщества поддерживают свои плагины адаптеров по лицензиям с открытым исходным кодом. Если вы заинтересованы в этом, мы рекомендуем:

* Размещение у общедоступного провайдера Git (например, GitHub или Gitlab)
* Публикация в [PyPI](https://pypi.org/)
* Добавление вашего адаптера в список [адаптеров сообщества](https://docs.getdbt.tech/docs/community-adapters.md) (см. раздел [Темы и страницы, которые необходимо охватить](#topics-and-pages-to-cover))

### Общие рекомендации

Чтобы лучше информировать сообщество dbt о новом адаптере, вы должны внести вклад в сайт документации с открытым исходным кодом dbt, который использует проект [Docusaurus](https://docusaurus.io/). Это сайт, на котором вы сейчас находитесь!

### Конвенции

Каждый `.md` файл, который вы создаете, нуждается в заголовке, как показано ниже. Идентификатор документа также нужно будет добавить в файл конфигурации: `website/sidebars.js`.

```md
---
title: "Документирование нового адаптера"
id: "documenting-a-new-adapter"
---
```

### Единый источник правды

Мы просим разработчиков, поддерживающих адаптеры, использовать [репозиторий docs.getdbt.com](https://github.com/dbt-labs/docs.getdbt.com) (то есть этот сайт) как единый источник достоверной документации, чтобы не приходилось поддерживать один и тот же набор сведений в трёх разных местах. Файл `README.md` в репозитории адаптера и страницы документации платформы данных должны просто ссылаться на соответствующую страницу этого сайта документации. Читайте далее, чтобы узнать, что следует и чего не следует размещать на сайте документации dbt.

### Предполагаемые знания

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

### Темы и страницы для охвата

Следующие темы должны быть рассмотрены на трех страницах этого сайта документации, чтобы ваша платформа данных была включена в нашу документацию. После того, как соответствующий запрос на слияние будет принят, мы просим вас ссылаться на эти страницы из `README` вашего репозитория адаптера, а также из документации вашего продукта.

Чтобы внести вклад, все, что вам нужно сделать, это внести изменения, указанные в таблице ниже.

| Как...                            | Файл для изменения в `/website/docs/`                           | Действие | Какую информацию включить                                                                                                                                                                                                                       |
| --------------------------------- | --------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Подключиться                      | `/docs/local/connect-data-platform/{MY-DATA-PLATFORM}-setup.md` | Создать  | Предоставьте всю информацию, необходимую для определения целевого подключения в `~/.dbt/profiles.yml` и успешного подключения к базе данных с помощью `dbt debug`. Следует упомянуть все возможные конфигурации.                                |
| Настроить                         | `reference/resource-configs/{MY-DATA-PLATFORM}-configs.md`      | Создать  | Какие параметры и настройки, специфичные для вашей платформы данных, необходимо знать пользователям? Например, параметры распределения таблиц и индексирования, политику column\_quoting, поддерживаемые стратегии инкрементального обновления. |
| Найти и установить                | `docs/community-adapters.md`                                    | Изменить | Добавьте адаптер в список адаптеров сообщества. Укажите, как установить Python-пакет адаптера, желательно с помощью pip и пакета из PyPI либо ссылки `git+` на репозиторий GitHub.                                                              |
| Добавить ссылку на боковую панель | `website/sidebars.js`                                           | Изменить | Добавьте id документа в соответствующее место меню боковой панели.                                                                                                                                                                              |

Например, предположим, что я хочу написать документацию для своего нового адаптера: `dbt-ders`. Для страницы «Подключение» я создам новый Markdown-файл `ders-setup.md` и добавлю его в каталог `/website/docs/local/connect-data-platform/`.

### Примеры PR для добавления новой документации адаптера

Ниже приведены некоторые недавние запросы на слияние, сделанные партнерами для документирования адаптера их платформы данных:

* [TiDB](https://github.com/dbt-labs/docs.getdbt.com/pull/1309)
* [SingleStore](https://github.com/dbt-labs/docs.getdbt.com/pull/1044)
* [Firebolt](https://github.com/dbt-labs/docs.getdbt.com/pull/941)

Примечание — Используйте следующий повторно используемый компонент для автоматического заполнения содержимого frontmatter на вашей новой странице:

```markdown
import SetUpPages from '/snippets/_setup-pages-intro.md';

<SetUpPages meta={frontMatter.meta} />
```

### Дальнейшее сопровождение

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

Основные возможности включают:

* материализации table, view и seed
* тесты dbt

Опишите на этом сайте, как подключаться с помощью адаптера и настраивать его, и поддерживайте эти страницы в актуальном состоянии. Список страниц, которые нужно добавить, см. в разделе [Темы и страницы, которые нужно осветить](#topics-and-pages-to-cover). О том, как управлять версиями выпусков и сохранять совместимость с dbt v1, см. в разделе [Управление версиями и выпуск адаптера](https://docs.getdbt.tech/guides/adapter-creation.md?step=2#versioning-and-releasing-your-adapter).

#### Следите за обновлениями dbt

Изучайте новые выпуски [dbt-adapters](https://github.com/dbt-labs/dbt-adapters) и обеспечивайте поддержку функций, применимых к вашей платформе.

#### Взаимодействуйте с сообществом

По возможности:

* Отвечайте на вопросы и помогайте пользователям начать работу в Slack сообщества dbt, в канале [#adapter-ecosystem](https://getdbt.slack.com/archives/C030A0UF5LM)
* Реагируйте на обращения (issues) в публичном репозитории адаптера
* Проверяйте и принимайте изменения от сообщества, если они подходят для проекта

#### Соблюдайте рекомендации по безопасности

Ваш адаптер не должен:

* Записывать учетные данные для доступа или данные из используемой платформы данных в журналы или файлы
* Выполнять вызовы API, кроме необходимых для работы функций dbt, или добавлять избыточное журналирование
* Скрывать код или поведение так, чтобы их было трудно проверить

Чтобы снизить риски, связанные с цепочкой поставок ПО:

* Используйте автоматизированный сервис для обновления зависимостей Python (например, Dependabot)
* Публикуйте пакет в PyPI из репозитория адаптера с помощью процесса CI/CD (например, GitHub Actions)
* Ограничьте административный доступ к репозиторию кода (GitHub) и репозиторию пакетов (PyPI)
* Выполняйте сканирование на уязвимости безопасности в CI/CD (например, с помощью Snyk)

Запустите набор тестов адаптера, описанный в разделе [Тестирование адаптера](https://docs.getdbt.tech/guides/adapter-creation.md?step=4).

## Продвижение нового адаптера

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

Как выглядит искреннее взаимодействие? Это сложно определить явными правилами. Одно хорошее правило — относиться к людям с достоинством и уважением.

Участникам сообщества следует воспринимать вклад в его развитие *как самоцель,* а не как средство достижения других бизнес-показателей (привлечения потенциальных клиентов, увеличения числа участников сообщества и прочего). [Мы — компания, движимая миссией.](https://www.getdbt.com/dbt-labs/values/) Вот несколько способов понять, насколько искренне вы участвуете в жизни сообщества:

* Является ли *основной* целью взаимодействия обмен знаниями и ресурсами или построение вовлеченности бренда?
* Представьте, что вы не работаете в той организации, в которой работаете — можете ли вы представить себе, что все равно пишете это?
* Написано ли это в формальном / маркетинговом языке или это звучит как вы, человек?

### Кто должен присоединиться к Slack-сообществу dbt?

* Люди, которые понимают, что значит заниматься практической работой в области [аналитической инженерии](https://www.getdbt.com/analytics-engineering/) Slack-сообщество dbt в первую очередь предназначено для взаимодействия аналитиков друг с другом — чем ближе пользователи в сообществе к реальной работе с данными/аналитической инженерией, тем более естественным будет их участие (что приведет к лучшим результатам для партнеров и сообщества).

* Практики DevRel с сильной концентрацией Практики DevRel часто имеют сильный аналитический опыт и хорошее понимание сообщества. Важно, чтобы они были сосредоточены на *вкладе*, а не на управлении метриками сообщества для партнерской организации (например, регистрация людей в их Slack или на мероприятия). Метрики будут расти естественным образом через подлинное взаимодействие.

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

* Инженеры-программисты, работающие над партнёрскими продуктами и разрабатывающие и поддерживающие интеграции с dbt v1 или dbt platform Такое участие наиболее эффективно, когда инженеры знакомы с dbt как продуктом или хотя бы прошли наш учебный курс. Slack часто становится первым местом, где конечные пользователи задают вопросы и делятся отзывами, поэтому рекомендуется присутствие в нём технического специалиста из команды. Также есть несколько каналов для разработчиков интеграций, которые обычно служат ценным источником знаний.

### Кто может испытывать трудности в сообществе dbt

* Люди в маркетинговых ролях Slack dbt не является маркетинговым каналом. Попытки использовать его в таком качестве неизменно терпят неудачу и могут даже привести к негативному восприятию продукта. Это не означает, что dbt не может служить маркетинговым целям, но долгосрочная приверженность взаимодействию является единственным проверенным методом для этого.

* Специалисты по продукту Сообщество dbt может стать бесценным источником обратной связи о продукте. Получать её можно двумя основными способами — естественным образом (когда участники сообщества сами предлагают новую функцию) и через прямые обращения с просьбой оставить отзыв или принять участие в пользовательском исследовании. Призывы к немедленному участию необходимо размещать в вашем выделенном канале #tools. Прямые обращения следует использовать умеренно, поскольку они могут заглушить более естественные обсуждения и обратную связь.

### Кто является аудиторией для выпуска адаптера?

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

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

Пользователи базы данных будут вашей основной аудиторией и наиболее полезными для достижения успеха. Взаимодействуйте с ними напрямую в выделенном канале Slack адаптера. Если такого канала еще нет, обратитесь в #channel-requests, и мы создадим его для вас и включим в объявление о новых каналах.

Последняя группа — это та, где становится важным взаимодействие с сообществом вне Slack. Twitter и LinkedIn — отличные места для взаимодействия с широкой аудиторией. Хорошо организованный выпуск адаптера может вызвать значительное и подлинное взаимодействие.

### Как сообщить о начальном выпуске и последующем контенте

Расскажите историю, которая вовлечет пользователей dbt и сообщество. Подчеркните новые случаи использования и функциональность, которые открывает адаптер, так, чтобы это резонировало с каждым сегментом.

* Существующие пользователи вашей технологии, которые новички в dbt

  * Предоставьте общий обзор ценности, которую dbt принесет вашим пользователям. Это может опираться на сообщения и ключевые моменты dbt, изложенные в [точке зрения dbt.](https://docs.getdbt.tech/community/resources/viewpoint.md)
  * Приведите примеры развертывания, которые говорят о общей ценности dbt и вашего продукта.

* Пользователи, которые уже знакомы с dbt и сообществом

  * Подумайте об уникальных сценариях использования или преимуществах вашего адаптера по сравнению с существующими адаптерами. Кого это заинтересует?
  * Вносите вклад в сообщество dbt и обеспечивайте качественную поддержку пользователей dbt, работающих с вашим адаптером (обучающие материалы, пакеты, документация и многое другое).
  * Пример запуска, интересного тем, кто уже знаком с dbt: [Firebolt](https://www.linkedin.com/feed/update/urn:li:activity:6879090752459182080/)

### Тактически управляйте распространением контента о новых или существующих адаптерах

Существуют тактические элементы о том, как и где делиться, которые помогают обеспечить успех.

* В Slack:

  * Канал #i-made-this — в этом канале действует политика против "маркетинга" и "контент-маркетинга", но он должен быть успешным, если вы напишете свой контент с учетом вышеуказанных рекомендаций. Даже с этим важно публиковать здесь умеренно.
  * Ваш собственный канал базы данных / инструмента — это место, где люди, которые выбрали получать от вас сообщения, и всегда отличное место для обмена тем, что для них актуально.

* В социальных сетях:

  * Twitter

  * LinkedIn

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

  * Спросите у вашего представителя партнера о:

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

#### Измерение вовлеченности

Вам не нужно 1000 человек в канале для успеха, но вам нужно как минимум несколько активных участников, которые могут сделать его живым. Если вам комфортно работать публично, это могут быть члены вашей команды, или это могут быть несколько человек, которых вы знаете, которые очень вовлечены и были бы заинтересованы в участии. Даже 2 или 3 постоянных участника в канале — это все, что нужно для успешного старта, и это, на самом деле, гораздо более значимо, чем 250 человек, которые никогда не публикуют сообщения.

### Как объявить о новом адаптере

Мы рекомендуем *не* использовать шаблонные объявления и поощряем поиск уникального голоса. Тем не менее, есть несколько вещей, которые мы хотели бы включить:

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

* Категории пользователей, которых может заинтересовать эта новость.

* Описание того, *что представляет собой* адаптер. Например:

  > С выходом нашего нового адаптера dbt вы сможете использовать dbt для моделирования и преобразования данных в \[name-of-your-org]

* Особые или уникальные сценарии использования или функциональные возможности, которые открывает адаптер.

* Планы по дальнейшей / текущей поддержке / разработке.

* Ссылка на документацию по использованию адаптера на сайте документации dbt Labs.

* Публикация с анонсом в блоге.

#### Объявление о новых версиях существующих адаптеров

Это может значительно варьироваться в зависимости от характера выпуска, но хорошей основой являются типы сообщений о выпуске, которые [мы публикуем в канале #dbt-releases](https://getdbt.slack.com/archives/C37J8BQEL/p1651242161526509).

[![Полная публикация о выпуске](/img/adapter-guide/0-full-release-notes.png?v=2 "Полная публикация о выпуске")](#)Полная публикация о выпуске

Разбивая это на части:

* Визуально отличительное объявление - сделайте его ясным, что это выпуск

  [![title](/img/adapter-guide/1-announcement.png?v=2 "title")](#)title
* Краткое письменное описание того, что входит в выпуск

  [![description](/img/adapter-guide/2-short-description.png?v=2 "description")](#)description
* Ссылки на дополнительные ресурсы

  [![more resources](/img/adapter-guide/3-additional-resources.png?v=2 "more resources")](#)more resources
* Инструкции по реализации:

  [![more installation](/img/adapter-guide/4-installation.png?v=2 "more installation")](#)more installation
* Признание вклада (если применимо)

  [![thank yous](/img/adapter-guide/6-thank-contribs.png?v=2 "thank yous")](#)thank yous
