Data Connect のスキーマとコネクタのデプロイと管理

Firebase Data Connect サービスには次の 3 つの主要コンポーネントがあります。

  • 独自の SQL スキーマを持つ基盤となる PostgreSQL データベース
  • Data Connect アプリ スキーマ（.gql ファイルで宣言）
  • いくつかのコネクタ（.gql ファイルで宣言）。

SQL スキーマはデータの信頼できる情報源であり、Data Connect スキーマはコネクタがそのデータを表示する方法です。コネクタは、クライアントがそのデータにアクセスするために使用できる API を宣言します。

CLI を使用して Data Connect サービスをデプロイする場合は、SQL スキーマを移行してから Data Connect スキーマを更新し、各コネクタを更新します。

デプロイに関する重要なコンセプト

デプロイを完全に理解するには、スキーマとコネクタに関する主要なコンセプトを理解することが重要です。

スキーマのデプロイ

Data Connect スキーマのデプロイは、Cloud SQL データベースの SQL スキーマに影響します。Data Connect は、新しいデータベースを操作する場合でも、既存のデータベースを非破壊的に適応させる必要がある場合でも、デプロイ中にスキーマを移行するのに役立ちます。

Data Connect スキーマ移行には、厳密と互換性の 2 つの異なるスキーマ検証モードがあります。

  • 厳格モードの検証では、アプリケーション スキーマを更新する前に、データベース スキーマがアプリケーション スキーマと完全に一致している必要があります。Data Connect スキーマで使用されていないテーブルまたは列は、データベースから削除されます。

  • 互換モードの検証では、アプリケーション スキーマを更新する前に、データベース スキーマがアプリケーション スキーマと互換性がある必要があります。スキーマ、テーブル、列を削除する追加の変更は任意です。

    互換性がある場合、スキーマの移行は、アプリケーション スキーマで参照されるテーブルと列にのみ影響します。アプリケーション スキーマで使用されていないデータベース内の要素は変更されません。そのため、デプロイ後にデータベースに未使用のものが含まれることがあります。

    • スキーマ
    • テーブル
    • 列

コネクタのデプロイ

Data Connect クエリとミューテーションは、クライアント コードによって送信されず、サーバーで実行されます。代わりに、デプロイ時に、これらの Data Connect オペレーションは Cloud Functions のようにサーバーに保存されます。つまり、デプロイによって既存のユーザーが機能しなくなる可能性があります。

デプロイのワークフローに沿って対応する

Data Connect プロジェクトは、ローカル プロジェクト ディレクトリと Firebase コンソールの両方で操作できます。

推奨されるデプロイ フローは次のとおりです。

  1. firebase dataconnect:services:list を使用して、現在デプロイされているスキーマとコネクタを一覧表示します。
  2. スキーマの更新の管理。
    1. firebase dataconnect:sql:diff を使用して、Cloud SQL データベースとローカル Data Connect スキーマの SQL スキーマの違いを確認します。
    2. 必要に応じて、dataconnect:sql:migrate を使用して SQL スキーマの移行を行います。
  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 デプロイでは、SQL スキーマが Data Connect スキーマと一致しているかどうかが引き続き確認され、互換性がない場合は警告とプロンプトが表示されます。

選択したリソースをデプロイする

より詳細に制御してデプロイするには、serviceId 引数を指定して --only フラグを使用します。特定のサービスのスキーマ変更のみをデプロイするには:

firebase deploy --only dataconnect:serviceId:schema

指定したコネクタとサービスのすべてのリソースをデプロイすることもできます。

firebase deploy --only dataconnect:serviceId:connectorId

最後に、1 つのサービスに対してスキーマとすべてのコネクタをデプロイできます。

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 CLI リファレンスをご覧ください。

スキーマとコネクタを管理するためのベスト プラクティス

Firebase では、Data Connect プロジェクトで推奨されるベスト プラクティスがいくつかあります。

互換性のない変更を最小限に抑える

  • Data Connect スキーマとコネクタ ファイルはソース管理に保存することをおすすめします。
  • 可能であれば、破壊的変更は避けてください。破壊的変更の一般的な例を次に示します。
    • スキーマからフィールドを削除する
    • スキーマ内の null 値を許容するフィールドを null 値を許容しないフィールドにする（例: Int -> Int!）
    • スキーマ内のフィールドの名前を変更する。
  • スキーマからフィールドを削除する必要がある場合は、影響を最小限に抑えるために、フィールドを複数のデプロイに分割することを検討してください。
    • まず、コネクタ内のフィールドへの参照をすべて削除し、変更をデプロイします。
    • 次に、新しく生成された SDK を使用するようにアプリを更新します。
    • 最後に、スキーマ .gql ファイルのフィールドを削除し、SQL スキーマを移行して、もう一度デプロイします。

新しいデータベースを操作する場合は厳格モードを使用する

新しいデータベースで Data Connect を使用していて、アプリケーション スキーマを積極的に開発しており、データベース スキーマがアプリケーション スキーマと完全に一致するようにしたい場合は、dataconnect.yaml に schemaValidation: "STRICT" を指定できます。

これにより、オプションの変更も適用されます。

データベースに本番環境データがある場合は互換モードを使用

本番環境データを含むデータベースに変更を加える場合は、既存のデータが削除されないように、互換モードでスキーマ移行を実行することをおすすめします。dataconnect.yaml で schemaValidation: "COMPATIBLE" を指定できます。

互換モードでは、必要なスキーマ移行の変更のみがデータベースに適用されます。

  • DROP SCHEMA、DROP TABLE、DROP COLUMN はオプションのステートメントと見なされ、データベース スキーマにアプリケーション スキーマで定義されていないスキーマ、テーブル、列が含まれていても、プランには生成されません。
  • データベース テーブルに、アプリケーション スキーマに含まれていない null 以外の列が含まれている場合、NOT NULL 制約は削除されます。これにより、定義済みのコネクタを使用してテーブルにデータを追加できます。

次のステップ