Подключение к Snowflake Общедоступно (GA) Совместимо с dbt v2

Изменение размера столбцов в Snowflake

Snowflake планирует увеличить размер столбцов по умолчанию для строковых и двоичных типов данных в сентябре 2026 года. После внедрения этого изменения в версиях dbt-snowflake ниже v1.10.6 могут возникать ошибки при построении некоторых инкрементальных моделей.

 Оценка влияния и необходимые действия

Если вы используете версию dbt-snowflake ниже v1.10.6 или ещё не перешли на канал выпуска в dbt platform, ваша версия адаптера несовместима с этим изменением. Это может приводить к ошибкам при построении инкрементальных моделей, которые соответствуют обоим следующим условиям:

• Содержат строковые столбцы с заданными правилами сортировки (collation)
• Используют настройку on_schema_change='sync_all_columns'

Чтобы проверить, затрагивает ли это изменение ваш проект, выполните следующую команду list:

dbt ls -s config.materialized:incremental,config.on_schema_change:sync_all_columns --resource-type model

Сообщить об ошибке в коде

• Если команда возвращает No nodes selected!, никаких действий не требуется.

• Если команда возвращает одну или несколько моделей (например, Found 1000 models, 644 macros), изменение может затронуть вас, если в этих моделях есть строковые столбцы без явно указанной длины. В этом случае обновитесь до версии, содержащей исправление:

  • dbt v1: dbt-snowflake v1.10.6 или более поздняя версия. Указания по обновлению приведены в разделе Обновление адаптеров инструкции по установке dbt v1.
  • dbt platform: любой канал выпуска (v1 Latest, v1 Compatible, v1 Extended или v1 Fallback).
  • dbt v2: v2.0.0.

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

Подключения и учётные данные в dbt platform наследуют права доступа настроенных учётных записей. Вы можете настроить роли и связанные с ними права доступа в Snowflake в соответствии с требованиями вашей компании и детально настроить доступ к объектам баз данных в вашей учётной записи.

Подробнее о настройке ролей в Snowflake см. в разделе Права доступа в Snowflake. Сведения о том, какие функции Snowflake поддерживаются в dbt v2 в режиме strict, см. в разделе Поддержка функций Snowflake.

Права доступа к вычислительному складу для dbt v2

Пользователь или служебная учётная запись Snowflake, от имени которых подключается dbt v2, должны иметь возможность выполнять рабочие нагрузки dbt (запросы, операции с метаданными и стандартные материализации). Предоставьте привилегии через роль Snowflake, назначенную этому пользователю.

Необходимые объекты Snowflake

Перед подключением должны существовать следующие объекты:

Объект	Назначение
Аккаунт	Идентификатор вашего аккаунта Snowflake
Пользователь	Служебная учётная запись или пользователь для dbt v2
Роль	Роль с необходимыми привилегиями, назначенная пользователю
Виртуальный склад	Виртуальный склад для выполнения вычислений
База данных	Целевая база данных или базы данных для моделей dbt
Схема	Целевая схема или схемы в базе данных

Основные операции

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

Разрешение	Объект	Назначение
USAGE	Виртуальный склад	Выполнение запросов
USAGE	База данных	Доступ к базе данных
USAGE	Схема	Доступ к схемам
SELECT	Таблицы или представления	Чтение существующих данных и источников
CREATE TABLE	Схема	Создание моделей, материализованных в виде таблиц
CREATE VIEW	Схема	Создание моделей, материализованных в виде представлений
INSERT	Таблицы	Загрузка данных в таблицы
UPDATE	Таблицы	Обновление инкрементальных моделей
DELETE	Таблицы	Инкрементальные модели с удалением и вставкой данных
TRUNCATE	Таблицы	Полное обновление инкрементальных моделей
DROP	Таблицы или представления	Замена существующих объектов

Операции с метаданными

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

Разрешение	Объект	Назначение
USAGE	INFORMATION_SCHEMA	Запрос метаданных таблиц и столбцов
DESCRIBE TABLE	Таблицы	Получение информации о структуре таблиц
SHOW OBJECTS	Схема	Получение списка отношений в схеме
SHOW USER FUNCTIONS	Схема	Обнаружение UDF (если используются)

Управление схемами и базами данных

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

Разрешение	Объект	Когда требуется
CREATE SCHEMA	База данных	Если dbt должен автоматически создавать схемы
CREATE DATABASE	Аккаунт	Если dbt должен автоматически создавать базы данных

Расширенные возможности

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

Разрешение	Объект	Возможность
CREATE STAGE	Схема	Промежуточное размещение файлов для seeds или снимков
CREATE FILE FORMAT	Схема	Пользовательские форматы файлов
CREATE SEQUENCE	Схема	Последовательности
EXECUTE TASK	Схема	Задачи Snowflake

Примеры ролей в Snowflake см. в разделе Права доступа в Snowflake.

Поля подключения

При создании подключения к Snowflake необходимо заполнить следующие поля:

Поле	Описание	Примеры
Account	Учётная запись Snowflake, к которой нужно подключиться. Посмотрите здесь, как должно выглядеть значение поля Account в зависимости от вашего региона.	✅ db5261993 или db5261993.east-us-2.azure   ❌ db5261993.eu-central-1.snowflakecomputing.com
Role	Обязательное поле, указывающее роль, которую следует использовать после подключения к Snowflake	transformer
Database	Логическая база данных, к которой нужно подключиться и в которой будут выполняться запросы.	analytics
Warehouse	Виртуальный вычислительный склад, используемый для выполнения запросов.	transforming

Методы аутентификации

В этом разделе описаны различные методы аутентификации для подключения dbt к Snowflake. Учётные данные сред развёртывания (Production, Staging, General) настраиваются глобально в разделе Connections настроек Account settings. Отдельные пользователи настраивают свои учётные данные в разделе Credentials своего профиля.

Аутентификация Snowflake на платформе dbt

В dbt platform нельзя создавать новые учётные данные Snowflake с использованием имени пользователя и пароля. Для новых учётных данных разработки и развёртывания по умолчанию используется аутентификация с помощью пары ключей. Для пользовательских учётных данных на тарифах уровня Enterprise также доступен Snowflake OAuth, если он настроен для подключения. Чтобы обновить существующие учётные данные с паролем, см. раздел Имя пользователя и пароль с MFA.

Пара ключей

Доступно в: средах разработки, средах развёртывания

Если вы впервые создаёте учётные данные Snowflake в dbt platform, по умолчанию используется аутентификация с помощью пары ключей. Используйте её для учётных данных как разработки, так и развёртывания. Метод аутентификации Keypair использует аутентификацию с помощью пары ключей Snowflake для проверки учётных данных разработки или развёртывания проекта dbt.

1. После создания зашифрованной пары ключей обязательно задайте rsa_public_key для пользователя Snowflake, который будет проходить аутентификацию в dbt:

   alter user jsmith set rsa_public_key='MIIBIjANBgkqh...';   

   Сообщить об ошибке в коде

2. Затем заполните поля Private Key и Private Key Passphrase на странице Credentials, чтобы завершить настройку аутентификации dbt в Snowflake с помощью пары ключей.

   • Примечание: допускается использование незашифрованных закрытых ключей. Используйте парольную фразу только при необходимости. В dbt можно указать private_key непосредственно в виде строки вместо private_key_path. Эта строка private_key может содержать ключ в формате DER с кодировкой Base64, представляющий байты ключа, или в текстовом формате PEM. Подробнее о создании ключей см. в документации Snowflake.
   • Указание закрытого ключа с помощью переменной окружения (например, {{ env_var('DBT_PRIVATE_KEY') }}) не поддерживается.

3. Для правильного заполнения поля Private Key обязательно включите строки-комментарии. Если вы получаете ошибку Could not deserialize key data или JWT token, подробнее см. в разделе Устранение неполадок.

Пример:

-----BEGIN ENCRYPTED PRIVATE KEY-----
< encrypted private key contents here - line 1 >
< encrypted private key contents here - line 2 >
< ... >
-----END ENCRYPTED PRIVATE KEY-----

Сообщить об ошибке в коде

Аутентификация Snowflake с помощью пары ключей

Пара ключей в dbt v2

Мы рекомендуем использовать формат PKCS#8 с шифрованием AES-256 для аутентификации с помощью пары ключей в dbt v2. dbt v2 не поддерживает устаревшее шифрование 3DES и форматы ключей без заголовка. Использование устаревших форматов ключей может привести к сбоям аутентификации.

Если вы столкнулись с ошибкой Key is PKCS#1 (RSA private key). Snowflake requires PKCS#8, ваш закрытый ключ имеет неверный формат. У вас есть два варианта:

• (Рекомендуемое решение) Повторно экспортируйте ключ с использованием современного шифрования:

  # Convert to PKCS#8 with AES-256 encryption
  openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 aes-256-cbc -inform PEM -out rsa_key.p8

  Сообщить об ошибке в коде

• (Временное решение) Добавьте заголовок BEGIN и завершающую строку END к телу PEM:

  -----BEGIN ENCRYPTED PRIVATE KEY-----
  < Your existing encrypted private key contents >
  -----END ENCRYPTED PRIVATE KEY-----

  Сообщить об ошибке в коде

Snowflake OAuth

Доступно в: средах разработки, только на тарифах уровня Enterprise

Метод аутентификации OAuth позволяет dbt выполнять запросы в среде разработки от имени пользователя Snowflake без настройки пароля Snowflake в dbt.

Подробнее о настройке подключения Snowflake OAuth в dbt см. в документации по настройке Snowflake OAuth.

Настройка подключения Snowflake OAuth

Переход с имени пользователя и пароля

Если ваши учётные данные по-прежнему используют имя пользователя и пароль, вы можете просмотреть существующую конфигурацию в разделе Credentials, профилях подключений или формах учётных данных развёртывания, но не сможете сохранить изменения, пока не переключите Auth method на пару ключей или OAuth. Если учётные данные с паролем всё ещё используются, в верхней части вашей учётной записи также может отображаться предупреждающий баннер.

Чтобы отказаться от использования имени пользователя и пароля, выполните действия из раздела Пара ключей или Snowflake OAuth.

Имя пользователя и пароль с MFA

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

Если при планировании перехода вы всё ещё используете имя пользователя и пароль, Snowflake требует MFA для всех входов с паролем. Поддержка MFA в Snowflake обеспечивается сервисом Duo Security.

• В dbt задайте следующий расширенный атрибут на странице General settings среды разработки в разделе Extended attributes:

  authenticator: username_password_mfa

  Сообщить об ошибке в коде

• Чтобы уменьшить количество запросов подтверждения при подключении к Snowflake с MFA, включите кэширование токенов в Snowflake.

• Если пользователи пропускают запросы подтверждения и их учётные записи Snowflake блокируются, при необходимости можно отключить автоматические повторные попытки, добавив следующую настройку в тот же раздел Extended attributes:

  connect_retries: 0

  Сообщить об ошибке в коде

Настройка имени пользователя и пароля с MFA, а также connect_retries в параметрах среды разработки.

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

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

URL с пользовательским доменом

Чтобы подключиться к Snowflake через пользовательский домен (vanity URL), а не через идентификатор учётной записи (account locator), используйте расширенные атрибуты, указав пользовательский домен в параметре host:

host: https://custom_domain_to_snowflake.com

Сообщить об ошибке в коде

Эта конфигурация может конфликтовать со Snowflake OAuth при использовании PrivateLink. Если пользователи не могут получить доступ к серверам аутентификации Snowflake из-за сетевых ограничений, обратитесь в службу поддержки dbt, чтобы найти обходное решение для такой архитектуры.

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

Если вы получаете ошибку Could not deserialize key data или JWT token, ознакомьтесь со следующими причинами и решениями:

 Ошибка: `Could not deserialize key data`

Возможная причина и решение ошибки «Could not deserialize key data» в dbt.

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

Решение:

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

 Ошибка: `JWT token`

Возможные причины и решения ошибки «JWT token» в dbt.

• Это может быть временная проблема взаимодействия между Snowflake и dbt. При подключении к Snowflake dbt получает JWT-токен, действительный только в течение 60 секунд. Если за это время Snowflake не ответит, в dbt может появиться ошибка JWT token is invalid.
• Открытый ключ был некорректно указан в Snowflake.

Решения

• dbt необходимо повторить попытку подключения к Snowflake.
• Проверьте открытый ключ в Snowflake и введите его корректно. Кроме того, вы можете обратиться за помощью в Snowflake или ознакомиться с дополнительными сведениями в этой статье Snowflake: Ошибка аутентификации по ключу с сообщением JWT token is invalid.

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

Создать GitHub Issue