Развертывание схем и соединителей Data Connect и управление ими.

Сервис Firebase Data Connect состоит из трех основных компонентов:

  • Базовая база данных PostgreSQL со своей собственной SQL-схемой.
  • Схема приложения Data Connect (объявленная в ваших .gql файлах)
  • ряд коннекторов (объявленных в ваших .gql файлах и настроенных в файлах connector.yaml ).

Схема SQL является источником достоверной информации о ваших данных, схема Data Connect определяет, как ваши коннекторы могут видеть эти данные, а коннекторы объявляют API, которые ваши клиенты могут использовать для доступа к этим данным.

При развертывании службы Data Connect с помощью CLI вам потребуется перенести схему SQL, затем обновить схему Data Connect , а затем обновить каждый из ваших коннекторов.

Важные концепции развертывания

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

Развертывание схем

Развертывание схемы Data Connect влияет на схему SQL для вашей базы данных Cloud SQL. Data Connect помогает вам мигрировать схемы во время развертывания, независимо от того, работаете ли вы с новой базой данных или вам необходимо неразрушающим образом адаптировать существующую базу данных.

Для миграции схем Data Connect доступны два различных режима проверки схемы: строгий и совместимый .

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

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

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

    • Схемы
    • Таблицы
    • Колонки

Развертывание коннекторов

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

Data Connect интегрирует анализ критических изменений в обновлениях вашего коннектора в интерфейс командной строки Firebase .

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

Например:

  • Изменения в коннекторе, которые могут повлиять на поведение клиента, включают удаление поля, допускающего значение NULL, из запроса без аннотации @retired schema.
  • Изменения в коннекторе, которые могут привести к сбоям в работе клиентов, включают изменение переменной операции, допускающей значение NULL, на переменную, допускающую значение NULL, без указания значения по умолчанию, или изменение типа данных поля на несовместимый (например, String на Int ).

Более полный список сценариев, требующих предупреждения и прерывания работы системы, приведен в справочном руководстве по интерфейсу командной строки .

Следуйте алгоритму развертывания.

Вы можете работать над проектом Data Connect как в локальной директории проекта, так и в консоли Firebase .

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

  1. Отображение списка развернутых в данный момент схем и коннекторов с помощью firebase dataconnect:services:list .
  2. Управление обновлениями схемы .
    1. Проверьте наличие различий в схеме SQL между вашей базой данных Cloud SQL и локальной схемой Data Connect с помощью firebase dataconnect:sql:diff .
    2. При необходимости выполните миграцию схемы SQL с помощью dataconnect:sql:migrate .
  3. Выполнение развертывания схемы и коннекторов осуществляется с помощью команды firebase deploy , как для самой схемы, так и для коннекторов, или для их комбинаций.

Развертывание и управление ресурсами Data Connect .

Перед развертыванием рекомендуется проверить работоспособность производственных ресурсов.

firebase dataconnect:services:list

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

При использовании любой команды deploy флаг --only dataconnect позволяет отделить развертывания Data Connect от других продуктов в вашем проекте.

Стандартное развертывание 

firebase deploy --only dataconnect

В этом стандартном режиме развертывания Firebase CLI пытается развернуть вашу схему и коннекторы.

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

Также перед обновлением схемы Data Connect проверяется, что схема SQL уже перенесена. Если нет, система автоматически предлагает выполнить необходимые шаги для миграции схем .

--force развертывание флага 

firebase deploy --only dataconnect --force

Если ни проверка коннектора, ни проверка схемы SQL не вызывают опасений, вы можете повторно запустить команду с --force , чтобы игнорировать их.

Параметр --force deploy по-прежнему проверяет, соответствует ли схема SQL схеме Data Connect , предупреждает о несовместимости и запрашивает подтверждение.

Развернуть выбранные ресурсы

Для более детального контроля развертывания используйте флаг --only с аргументом serviceId . Чтобы развернуть только изменения схемы для конкретной службы:

firebase deploy --only dataconnect:serviceId:schema

Вы также можете развернуть все ресурсы для указанного коннектора и службы.

firebase deploy --only dataconnect:serviceId:connectorId

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

firebase deploy --only dataconnect:serviceId

Откат развертывания

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

Миграция схем баз данных

Если вы быстро создаёте прототипы, экспериментируете со схемами и знаете, что изменения в схеме носят деструктивный характер, вы можете использовать инструменты Data Connect для проверки изменений и контроля за процессом обновления.

Различия в изменениях схемы SQL

Вы можете проверить изменения:

firebase dataconnect:sql:diff

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

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

Применить изменения

Когда вы будете удовлетворены и готовы развернуть изменения в схеме экземпляра Cloud SQL, выполните команду firebase dataconnect:sql:migrate . Вам будет предложено подтвердить изменения.

firebase dataconnect:sql:migrate [serviceId]

В интерактивных средах отображаются операторы миграции SQL и подсказки о дальнейших действиях.

Миграция в строгом или совместимом режиме.

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

Вы можете изменить это поведение, отредактировав файл dataconnect.yaml . Раскомментируйте ключ schemaValidation и объявите COMPATIBLE , чтобы в миграциях применялись только необходимые изменения.

schemaValidation: "COMPATIBLE"

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

schemaValidation: "STRICT"

Для получения дополнительной информации см. справочник по интерфейсу командной строки Data Connect .

Обновить коннекторы

При выполнении firebase deploy интерфейс командной строки инициирует обновление соответствующих коннекторов и выдает предупреждения (могут повлиять на поведение клиента) и сообщения о возможных или недопустимых сбоях (возможно или наверняка приведут к сбоям).

Управление обновлениями коннектора с помощью интерфейса командной строки.

Интерфейс командной строки (CLI) ведет себя несколько по-разному в интерактивном и неинтерактивном режимах.

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

# Prompts for acceptance for any warning-level or breaking-level changes prior
# to deploying connectors.
firebase deploy --only dataconnect
# Will deploy connectors without prompting.
firebase deploy --only dataconnect --force

В неинтерактивном режиме CLI будет развертывать ваш коннектор до тех пор, пока не будет оценок критических уровней. В противном случае ваш скрипт завершит работу с журналом критических изменений. Вы можете переопределить и развернуть его, установив флаг --force . 

# Will deploy connectors with warning-level changes. If any breaking changes
# are present, the deploy will fail and output any breaking changes
firebase deploy --only dataconnect --non-interactive
# Will deploy the connectors from the previous step, if the same issues are present.
firebase deploy --only dataconnect --non-interactive --force

Для получения более подробной информации см. справочное руководство по интерфейсу командной строки .

Рекомендации по управлению схемами и коннекторами

Firebase рекомендует ряд практик, которым следует следовать в проектах Data Connect .

Сведите к минимуму изменения, нарушающие правила.

  • Firebase рекомендует хранить файлы схемы и коннектора Data Connect в системе контроля версий.
  • По возможности избегайте критических изменений. К распространённым примерам критических изменений относятся:
    • Удаление поля из схемы
    • Преобразование поля, допускающего значение NULL, в вашей схеме в поле, допускающее значение NULL, в поле, допускающее значение NULL (например, Int -> Int! ).
    • Переименование поля в вашей схеме.
  • Если вам необходимо удалить поле из схемы, рассмотрите возможность разделения процесса на несколько развертываний, чтобы минимизировать последствия:
    • Сначала удалите все ссылки на это поле в ваших коннекторах и примените изменения.
    • Далее обновите свои приложения, чтобы использовать новые сгенерированные SDK.
    • Наконец, удалите поле в файле схемы .gql , выполните миграцию вашей SQL-схемы и снова выполните развертывание.

При работе с новыми базами данных используйте строгий режим.

Если вы используете Data Connect с новой базой данных и активно разрабатываете схему своего приложения, и хотите убедиться, что схема вашей базы данных точно соответствует схеме вашего приложения, вы можете указать schemaValidation: "STRICT" в файле dataconnect.yaml .

Это обеспечит применение и необязательных изменений.

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

Если вы вносите изменения в базу данных, содержащую производственные данные, мы рекомендуем выполнять миграции схемы в совместимом режиме, чтобы гарантировать, что существующие данные не будут удалены. Вы можете указать schemaValidation: "COMPATIBLE" в файле dataconnect.yaml .

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

  • DROP SCHEMA , DROP TABLE и DROP COLUMN считаются необязательными и не будут сгенерированы для вашего плана, даже если схема вашей базы данных содержит схемы, таблицы или столбцы, не определенные в схеме вашего приложения.
  • Если в вашей таблице базы данных есть столбец, не содержащий значений NULL, который не включен в схему вашего приложения, ограничение NOT NULL будет снято, поэтому данные по-прежнему можно будет добавлять в таблицу с помощью определенных вами коннекторов.

Что дальше?