Развертывание схем и соединителей 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 CLI.

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

Например:

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

Более подробный список сценариев уровня предупреждения и уровня нарушения приведен в справочном руководстве CLI .

Следуйте рабочему процессу развертывания

Вы можете работать над проектом 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 пытается развернуть вашу схему и коннекторы.

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

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

--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 для проверки изменений и контроля за тем, как выполняются обновления.

Изменения в схеме Diff 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 CLI.

Обновление соединителей

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

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

Поведение 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

Более подробную информацию см. в справочном руководстве CLI .

Лучшие практики управления схемами и коннекторами

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

Минимизируйте критические изменения

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

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

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

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

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

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

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

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

Что дальше?