SQL Connect のスキーマとコネクタをデプロイして管理する

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

  • 独自の SQL スキーマ を持つ基盤となる PostgreSQL データベース
  • SQL Connect アプリケーション スキーマ （.gql ファイルで宣言）
  • 多数のコネクタ （.gql ファイルで宣言、connector.yaml ファイルで構成）。

SQL スキーマはデータの信頼できる唯一の情報源であり、SQL Connect スキーマはコネクタがそのデータをどのように認識するかを示します。コネクタは、クライアントがそのデータにアクセスするために使用できる API を宣言します。

CLI を使用して SQL Connect サービスをデプロイすると、 SQL スキーマが移行され、SQL Connect スキーマが更新され、 各コネクタが更新されます。

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

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

スキーマのデプロイ

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

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

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

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

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

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

コネクタのデプロイ

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

SQL Connect は、 コネクタの更新における破壊的変更の分析を Firebase CLI に統合します。

CLI は、スキーマに対する各コネクタの変更を分析し、クライアントの動作を変更する可能性のあるコネクタの変更（メッセージは警告レベル）または以前のバージョンのクライアント コードを破損する可能性のあるコネクタの変更（メッセージは破損レベル）に関する一連の評価メッセージを発行します。

次に例を示します。

  • クライアントの動作を変更する可能性のあるコネクタの変更には、@retired スキーマ アノテーションなしでクエリから null 許容フィールドを削除することが含まれます。
  • クライアントを破損する可能性のあるコネクタの変更には、デフォルト値なしで null 許容オペレーション変数を非 null に変更したり、フィールドのデータ型を互換性のないもの（String から Int など）に変更したりすることが含まれます。

警告レベルと破損レベルのシナリオの詳細なリストについては、CLI リファレンス ガイドをご覧ください。

デプロイ ワークフローに沿って操作する

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

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

  1. firebase dataconnect:services:list を使用して、現在デプロイされているスキーマとコネクタ を一覧表示します。
  2. スキーマの更新 を管理します。
    1. Cloud SQL データベースとローカル SQL Connect スキーマの SQL スキーマの違いを firebase dataconnect:sql:diff で確認します。
    2. 必要に応じて、dataconnect:sql:migrate を使用して SQL スキーマの移行を行います。
  3. firebase deploy を実行して、スキーマのみ、コネクタのみ、またはリソースの組み合わせのスキーマとコネクタのデプロイ を行います。

SQL Connect リソースをデプロイして管理する

デプロイを行う前に、本番環境リソースを確認することをおすすめします。

firebase dataconnect:services:list

ローカル プロジェクト ディレクトリで作業する場合、通常は firebase deploy コマンドを使用して、スキーマとコネクタを本番環境にデプロイします。このとき、インタラクティブなフィードバックが表示されます。

任意の deploy コマンドを使用すると、--only dataconnect フラグを使用して、 SQL Connect のデプロイをプロジェクト内の他のプロダクトから分離できます。

通常のデプロイ

firebase deploy --only dataconnect

この通常のデプロイでは、Firebase CLI がスキーマ とコネクタのデプロイを試みます。

新しいスキーマが既存のコネクタを破損していないことを検証します。 破壊的変更を行う場合は、ベスト プラクティスに従ってください。

また、 SQL Connect スキーマを更新する前に、SQL スキーマがすでに移行されていることを確認します。移行されていない場合は、スキーマを移行するために必要な 手順が自動的に表示されます。

--force フラグのデプロイ

firebase deploy --only dataconnect --force

コネクタまたは SQL スキーマの検証が問題にならない場合は、--force を指定してコマンドを再実行すると、検証を無視できます。

--force デプロイでは、SQL スキーマが SQL Connect スキーマと一致しているかどうかが確認され、非互換性がある場合は警告が表示されます。

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

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

firebase deploy --only dataconnect:serviceId:schema

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

firebase deploy --only dataconnect:serviceId:connectorId

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

firebase deploy --only dataconnect:serviceId

デプロイをロールバックする

手動でロールバックするには、コードの以前のバージョンをチェックアウトしてデプロイします。元のデプロイに破壊的な変更が含まれている場合、削除されたデータを完全に復元できない可能性があります。

データベース スキーマを移行する

プロトタイピングを迅速に行い、スキーマをテストし、スキーマの変更が破壊的であることがわかっている場合は、SQL 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"

詳細については、SQL 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 では、SQL Connect プロジェクトで従うべきいくつかのプラクティスを推奨しています。

破壊的変更を最小限に抑える

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

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

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

これにより、省略可能な変更も適用されます。

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

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

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

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

次のステップ