Настройка Microsoft SQL Server

Плагин сообщества

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

Поддерживается: Community
Авторы: Mikael Ene & dbt-msft community (https://github.com/dbt-msft)
Репозиторий на GitHub: dbt-msft/dbt-sqlserver
Пакет на PyPI: dbt-sqlserver
Канал в Slack: #db-sqlserver
Поддерживаемая версия dbt Core: v0.14.0 и новее
Поддержка dbt Cloud: Not Supported
Минимальная версия платформы данных: SQL Server 2016

Установка dbt-sqlserver

Используйте pip для установки адаптера. До версии 1.8 установка адаптера автоматически устанавливала dbt-core и любые дополнительные зависимости. Начиная с версии 1.8, установка адаптера не устанавливает автоматически dbt-core. Это связано с тем, что адаптеры и версии dbt Core были разделены, и мы больше не хотим перезаписывать существующие установки dbt-core. Используйте следующую команду для установки:

Конфигурация dbt-sqlserver

Для конфигурации, специфичной для SQL Server, пожалуйста, обратитесь к конфигурациям SQL Server.

Изменение настроек по умолчанию в dbt-sqlserver v1.2 / ODBC Driver 18

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

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

На Debian/Ubuntu убедитесь, что у вас есть заголовочные файлы ODBC перед установкой

sudo apt install unixodbc-dev

Скачайте и установите Microsoft ODBC Driver 18 для SQL Server. Если у вас уже установлен ODBC Driver 17, он также будет работать.

Поддерживаемые конфигурации

Адаптер тестировался с SQL Server 2017, SQL Server 2019, SQL Server 2022 и Azure SQL Database.
Мы тестируем все комбинации с Microsoft ODBC Driver 17 и Microsoft ODBC Driver 18.
Колляции, на которых мы проводим тесты: SQL_Latin1_General_CP1_CI_AS и SQL_Latin1_General_CP1_CS_AS.

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

Методы аутентификации и конфигурация профиля

Общая конфигурация

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

Параметр конфигурации	Описание	Тип	Пример
`driver`	ODBC-драйвер для использования	Обязательный	`ODBC Driver 18 for SQL Server`
`server`	Имя хоста сервера	Обязательный	`localhost`
`port`	Порт сервера	Обязательный	`1433`
`database`	Имя базы данных	Обязательный	Не применимо
`schema`	Имя схемы	Обязательный	`dbo`
`retries`	Количество автоматических попыток повторить запрос перед ошибкой. По умолчанию `1`. Запросы с синтаксическими ошибками не будут повторяться. Этот параметр можно использовать для преодоления временных сетевых проблем.	Необязательный	Не применимо
`login_timeout`	Количество секунд, используемых для установления соединения перед ошибкой. По умолчанию `0`, что означает, что тайм-аут отключен или используются системные настройки по умолчанию.	Необязательный	Не применимо
`query_timeout`	Количество секунд, используемых для ожидания запроса перед ошибкой. По умолчанию `0`, что означает, что тайм-аут отключен или используются системные настройки по умолчанию.	Необязательный	Не применимо
`schema_authorization`	Опционально укажите принципала, который должен владеть схемами, создаваемыми dbt. Подробнее о авторизации схем.	Необязательный	Не применимо
`encrypt`	Шифровать ли соединение с сервером. По умолчанию `true`. Подробнее о шифровании соединений.	Необязательный	Не применимо
`trust_cert`	Доверять ли сертификату сервера. По умолчанию `false`. Подробнее о шифровании соединений.	Необязательный	Не применимо

Шифрование соединений

Microsoft внесла несколько изменений в выпуске ODBC Driver 18, которые влияют на то, как настраивается шифрование соединений. Чтобы учесть эти изменения, начиная с dbt-sqlserver 1.2.0 или новее, значения по умолчанию для encrypt и trust_cert были изменены. Оба этих параметра теперь всегда будут включены в строку соединения с сервером, независимо от того, оставили ли вы их в конфигурации профиля или нет.

Значение по умолчанию для encrypt — true, что означает, что соединения по умолчанию шифруются.
Значение по умолчанию для trust_cert — false, что означает, что сертификат сервера будет проверен. Установив это значение в true, будет принят самоподписанный сертификат.

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

Стандартная аутентификация SQL Server

Учетные данные SQL Server поддерживаются как для локальных серверов, так и для Azure, и это метод аутентификации по умолчанию для dbt-sqlserver.

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

Учетные данные SQL Server
Учетные данные Windows

profiles.yml

your_profile_name:
  target: dev
  outputs:
    dev:
      type: sqlserver
      driver: 'ODBC Driver 18 for SQL Server' # (ODBC-драйвер, установленный в вашей системе)
      server: hostname или IP вашего сервера
      port: 1433
      database: database
      schema: schema_name
      user: username
      password: password

profiles.yml

your_profile_name:
  target: dev
  outputs:
    dev:
      type: sqlserver
      driver: 'ODBC Driver 18 for SQL Server' # (ODBC-драйвер, установленный в вашей системе)
      server: hostname или IP вашего сервера
      port: 1433
      database: exampledb
      schema: schema_name
      windows_login: True

Аутентификация Microsoft Entra ID

Хотя вы можете использовать аутентификацию с именем пользователя и паролем SQL, как указано выше, вы можете выбрать один из следующих методов аутентификации для Azure SQL.

Следующие дополнительные методы доступны для аутентификации в продуктах Azure SQL:

Имя пользователя и пароль Microsoft Entra ID (ранее Azure AD)
Сервисный принципал
Управляемая идентичность
Аутентификация на основе окружения
Аутентификация Azure CLI
Аутентификация VS Code (доступна через автоматический вариант ниже)
Аутентификация модуля Azure PowerShell (доступна через автоматический вариант ниже)
Автоматическая аутентификация

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

Имя пользователя и пароль Microsoft Entra ID
Сервисный принципал
Управляемая идентичность
На основе окружения
Azure CLI
Автоматическая

profiles.yml

your_profile_name:
  target: dev
  outputs:
    dev:
      type: sqlserver
      driver: 'ODBC Driver 18 for SQL Server' # (ODBC-драйвер, установленный в вашей системе)
      server: hostname или IP вашего сервера
      port: 1433
      database: exampledb
      schema: schema_name
      authentication: ActiveDirectoryPassword
      user: bill.gates@microsoft.com
      password: iheartopensource

Идентификатор клиента часто также называют идентификатором приложения.

profiles.yml

your_profile_name:
  target: dev
  outputs:
    dev:
      type: sqlserver
      driver: 'ODBC Driver 18 for SQL Server' # (ODBC-драйвер, установленный в вашей системе)
      server: hostname или IP вашего сервера
      port: 1433
      database: exampledb
      schema: schema_name
      authentication: ServicePrincipal
      tenant_id: 00000000-0000-0000-0000-000000001234
      client_id: 00000000-0000-0000-0000-000000001234
      client_secret: S3cret!

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

profiles.yml

your_profile_name:
  target: dev
  outputs:
    dev:
      type: sqlserver
      driver: 'ODBC Driver 18 for SQL Server' # (ODBC-драйвер, установленный в вашей системе)
      server: hostname или IP вашего сервера
      port: 1433
      database: exampledb
      schema: schema_name
      authentication: ActiveDirectoryMsi

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

Документация Microsoft по EnvironmentCredential объясняет доступные комбинации переменных окружения, которые вы можете использовать.

profiles.yml

your_profile_name:
  target: dev
  outputs:
    dev:
      type: sqlserver
      driver: 'ODBC Driver 18 for SQL Server' # (ODBC-драйвер, установленный в вашей системе)
      server: hostname или IP вашего сервера
      port: 1433
      database: exampledb
      schema: schema_name
      authentication: environment

Сначала установите Azure CLI, затем выполните вход:

az login

profiles.yml

your_profile_name:
  target: dev
  outputs:
    dev:
      type: sqlserver
      driver: 'ODBC Driver 18 for SQL Server' # (ODBC-драйвер, установленный в вашей системе)
      server: hostname или IP вашего сервера
      port: 1433
      database: exampledb
      schema: schema_name
      authentication: CLI

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

Следующие методы пробуются по порядку:

Аутентификация на основе окружения
Аутентификация с управляемой идентичностью
Аутентификация Visual Studio (только для Windows, игнорируется на других операционных системах)
Аутентификация Visual Studio Code
Аутентификация Azure CLI
Аутентификация модуля Azure PowerShell

profiles.yml

your_profile_name:
  target: dev
  outputs:
    dev:
      type: sqlserver
      driver: 'ODBC Driver 18 for SQL Server' # (ODBC-драйвер, установленный в вашей системе)
      server: hostname или IP вашего сервера
      port: 1433
      database: exampledb
      schema: schema_name
      authentication: auto

Дополнительные параметры для Microsoft Entra ID на Windows

На системах Windows также доступны следующие дополнительные методы аутентификации для Azure SQL:

Интерактивная аутентификация Microsoft Entra ID
Интегрированная аутентификация Microsoft Entra ID
Аутентификация Visual Studio (доступна через автоматический вариант выше)

Интерактивная аутентификация Microsoft Entra ID
Интегрированная аутентификация Microsoft Entra ID

Эта настройка может опционально показывать запросы многофакторной аутентификации.

profiles.yml

your_profile_name:
  target: dev
  outputs:
    dev:
      type: sqlserver
      driver: 'ODBC Driver 18 for SQL Server' # (ODBC-драйвер, установленный в вашей системе)
      server: hostname или IP вашего сервера
      port: 1433
      database: exampledb
      schema: schema_name
      authentication: ActiveDirectoryInteractive
      user: bill.gates@microsoft.com

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

profiles.yml

your_profile_name:
  target: dev
  outputs:
    dev:
      type: sqlserver
      driver: 'ODBC Driver 18 for SQL Server' # (ODBC-драйвер, установленный в вашей системе)
      server: hostname или IP вашего сервера
      port: 1433
      database: exampledb
      schema: schema_name
      authentication: ActiveDirectoryIntegrated

Автоматическое предоставление принципалов Microsoft Entra ID для грантов

В dbt 1.2 или новее вы можете использовать блок конфигурации grants для автоматического предоставления/отзыва разрешений на ваши модели пользователям или группам. Это полностью поддерживается в этом адаптере и имеет дополнительную функцию.

Установив auto_provision_aad_principals в true в конфигурации вашей модели, вы можете автоматически предоставлять принципалов Microsoft Entra ID (пользователей или группы), которые еще не существуют.

В Azure SQL вы можете войти, используя аутентификацию Microsoft Entra ID, но чтобы иметь возможность предоставить принципалу Microsoft Entra ID определенные разрешения, он должен быть сначала связан в базе данных. (Документация Microsoft)

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

Авторизация схем

Вы можете опционально указать принципала, который должен владеть всеми схемами, создаваемыми dbt. Это затем используется в операторе CREATE SCHEMA следующим образом:

CREATE SCHEMA [schema_name] AUTHORIZATION [schema_authorization]

Распространенный случай использования — это использование, когда вы аутентифицируетесь с принципалом, у которого есть разрешения на основе группы, такой как группа Microsoft Entra ID. Когда этот принципал создает схему, сервер сначала попытается создать индивидуальный логин для этого принципала, а затем связать схему с этим принципалом. Если бы вы использовали Microsoft Entra ID в этом случае, то это не удалось бы, так как Azure SQL не может автоматически создавать логины для отдельных лиц, входящих в группу AD.

Справка по всем параметрам соединения

Параметр конфигурации	Описание	Обязательный	Значение по умолчанию
`driver`	ODBC-драйвер для использования.	✅
`host`	Имя хоста сервера базы данных.	✅
`port`	Порт сервера базы данных.		`1433`
`database`	Имя базы данных для подключения.	✅
`schema`	Схема для использования.	✅
`authentication`	Метод аутентификации для использования. Это не требуется для аутентификации Windows.		`'sql'`
`UID`	Имя пользователя, используемое для аутентификации. Это можно не указывать в зависимости от метода аутентификации.
`PWD`	Пароль, используемый для аутентификации. Это можно не указывать в зависимости от метода аутентификации.
`windows_login`	Установите это значение в `true`, чтобы использовать аутентификацию Windows. Это доступно только для SQL Server.
`tenant_id`	Идентификатор арендатора экземпляра Microsoft Entra ID. Это используется только при подключении к Azure SQL с сервисным принципалом.
`client_id`	Идентификатор клиента сервисного принципала Microsoft Entra. Это используется только при подключении к Azure SQL с сервисным принципалом Microsoft Entra.
`client_secret`	Секрет клиента сервисного принципала Microsoft Entra. Это используется только при подключении к Azure SQL с сервисным принципалом Microsoft Entra.
`encrypt`	Установите это значение в `false`, чтобы отключить использование шифрования. См. выше.		`true`
`trust_cert`	Установите это значение в `true`, чтобы доверять сертификату сервера. См. выше.		`false`
`retries`	Количество попыток повторить неудачное соединение.		`1`
`schema_authorization`	Опционально укажите принципала, который должен владеть схемами, создаваемыми dbt. Подробнее выше.
`login_timeout`	Количество секунд ожидания до получения ответа от сервера при установлении соединения. `0` означает, что тайм-аут отключен.		`0`
`query_timeout`	Количество секунд ожидания до получения ответа от сервера при выполнении запроса. `0` означает, что тайм-аут отключен.		`0`

Допустимые значения для authentication:

sql: Аутентификация SQL с использованием имени пользователя и пароля
ActiveDirectoryPassword: Аутентификация Active Directory с использованием имени пользователя и пароля
ActiveDirectoryInteractive: Аутентификация Active Directory с использованием имени пользователя и запросов MFA
ActiveDirectoryIntegrated: Аутентификация Active Directory с использованием учетных данных текущего пользователя
ServicePrincipal: Аутентификация Microsoft Entra ID с использованием сервисного принципала
CLI: Аутентификация Microsoft Entra ID с использованием учетной записи, с которой вы вошли в Azure CLI
ActiveDirectoryMsi: Аутентификация Microsoft Entra ID с использованием управляемой идентичности, доступной в системе
environment: Аутентификация Microsoft Entra ID с использованием переменных окружения, как задокументировано здесь
auto: Аутентификация Microsoft Entra ID, пробующая предыдущие методы аутентификации, пока не найдет работающий

Установка dbt-sqlserver

Конфигурация dbt-sqlserver

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

Поддерживаемые конфигурации​

Методы аутентификации и конфигурация профиля​

Общая конфигурация​

Шифрование соединений​

Стандартная аутентификация SQL Server​

Аутентификация Microsoft Entra ID​

Дополнительные параметры для Microsoft Entra ID на Windows​

Автоматическое предоставление принципалов Microsoft Entra ID для грантов​

Авторизация схем​

Справка по всем параметрам соединения​

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

Поддерживаемые конфигурации

Методы аутентификации и конфигурация профиля

Общая конфигурация

Шифрование соединений

Стандартная аутентификация SQL Server

Аутентификация Microsoft Entra ID

Дополнительные параметры для Microsoft Entra ID на Windows

Автоматическое предоставление принципалов Microsoft Entra ID для грантов

Авторизация схем

Справка по всем параметрам соединения