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

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 будет снято, так что данные по-прежнему можно будет добавлять в таблицу с помощью определенных вами соединителей.

Что дальше?