firebase-data-connect

Firebase SQL Connect

Firebase SQL Connect は、GraphQL スキーマ、自動生成されるクエリ／ミューテーション、型安全な SDK を備えた、Cloud SQL for PostgreSQL を使用するリレーショナルデータベースサービスです。

メモ

製品名の変更：Firebase Data Connect の名称が Firebase SQL Connect に変更されました。このスキルリポジトリ内で「Data Connect」または「Firebase Data Connect」に言及している手順、参照、例は、「SQL Connect」および「Firebase SQL Connect」にも適用されます。

プロジェクト構成

dataconnect/
├── dataconnect.yaml      # Service configuration
├── seed_data.gql         # LOCAL ONLY — prototype/test data
├── schema/
│   └── schema.gql        # Data model (types with @table)
└── connector/
    ├── connector.yaml    # Connector config + SDK generation
    ├── queries.gql       # Queries
    └── mutations.gql     # Mutations

検証に使用する主なツール

プロジェクトが正しいことを確認するには、次の 2 つの方法を使用します。

1. GraphQL スキーマを確認する：ユーザー定義の拡張と生成された拡張の両方を確認します（.dataconnect/schema/main/）。
2. オペレーションを検証する：スキーマに対して npx -y firebase-tools@latest dataconnect:compile を実行します。

オペレーション戦略：GraphQL とネイティブ SQL

常に ネイティブ GraphQL をデフォルトとして使用します。ネイティブ SQL は型安全性がなく、スキーマで強制される構造を迂回します。ネイティブ SQL は、ユーザーから明示的に要求された場合、またはタスクで高度なデータベース機能が必要な場合にのみ使用してください。

戦略	使用する場面	実装
ネイティブ GraphQL（デフォルト）	ほとんどすべてのユースケース。標準的な CRUD、基本的なフィルタリング／並べ替え、シンプルなリレーショナル結合。完全な型安全性が必要です。	自動生成されるフィールド（movie_insert、movies）。強い型付けとスキーマによる制約。
ネイティブ SQL（高度）	PostgreSQL 拡張機能（PostGIS など）、ウィンドウ関数（RANK()）、複雑な集計、高度に最適化されたサブクエリ。	_select、_execute などで生の SQL 文字列リテラルを使用します。厳密な位置パラメーター（$1）が必要です。型安全性はありません。

開発ワークフロー

アプリケーションを構築するには、次の厳密なワークフローに従ってください。各ステップの構文と利用可能な機能を理解するため、リンク先のリファレンスファイルを必ず読んでください。

1. データモデルを定義する（schema/schema.gql）

GraphQL の型、テーブル、リレーションシップを定義します（これらは Postgres スキーマにマッピングされます）。

reference/schema.md を読んでください：

• @table、@col、@default
• リレーションシップ（@ref、1 対多、多対多）
• データ型（UUID、Vector、JSON など）

2. 認可された操作を定義する（connector/queries.gql、connector/mutations.gql）

認可ロジックを含め、クライアントで使用するクエリとミューテーションを記述します。SQL Connect はデフォルトで安全です。

認可については、reference/operations.md をお読みください。

• クエリ：フィルタリング（where）、並べ替え（orderBy）、ページネーション（limit／offset）。
• ミューテーション：作成（_insert）、更新（_update）、削除（_delete）。
• アップサート：_upsert を使用して、レコードを「挿入または更新」します（ユーザープロフィールでは非常に重要です）。
• トランザクション：複数ステップのアトミックな操作には @transaction を使用します。ステップ間でデータを渡すには _expr: "response.<prevStep>" を使用します。

認可については、reference/security.md をお読みください。

• PUBLIC、USER、NO_ACCESS には @auth(level: ...) を使用します。
• 行レベルのセキュリティと検証には @check と @redact を使用します。

リアルタイムサブスクリプションについては、reference/realtime.md をお読みください。

• 時間ベースのポーリングとイベント駆動型の更新には @refresh ディレクティブを使用します。
• リフレッシュのトリガーを正確に絞り込むには CEL 条件を使用します。

Native SQL 操作については、reference/native_sql.md をお読みください。

• _select、_selectFirst、_execute を使用した生 SQL の埋め込み
• 位置パラメーター（$1、$2）、引用符、CTE に関する厳格なルール
• PostgreSQL の高度な機能（PostGIS、ウィンドウ関数）

3. アプリで型安全な SDK を使用する

クライアントプラットフォーム向けに、型安全なコードを生成します。

connector.yaml で SDK の生成を設定します。

connectorId: my-connector
generate:
  javascriptSdk:
    outputDir: "../web-app/src/lib/dataconnect"
    package: "@movie-app/dataconnect"
  kotlinSdk:
    outputDir: "../android-app/app/src/main/kotlin/com/example/dataconnect"
    package: "com.example.dataconnect"
  swiftSdk:
    outputDir: "../ios-app/DataConnect"
    package: "DataConnectGenerated"

SDK を生成します。

npx -y firebase-tools@latest dataconnect:sdk:generate

生成された SDK の使用方法について、プラットフォーム別の手順をお読みください。

• Web（TypeScript）：reference/sdk_web.md
• Android（Kotlin）：reference/sdk_android.md
• iOS（Swift）：reference/sdk_ios.md
• Admin（Node.js）： reference/sdk_admin_node.md
• Flutter（Dart）：reference/sdk_flutter.md

---

機能と対応するリファレンス

特定の機能を実装する場合は、対応するリファレンスファイルを参照してください。

機能	リファレンスファイル	主な概念
データモデリング	reference/schema.md	@table、@unique、@index、リレーション
ベクトル検索	reference/search.md	Vector、@col(dataType: "vector")、埋め込み
全文検索	reference/search.md	@searchable、movies_search
データのアップサート	reference/operations.md	_upsert ミューテーション
複雑なフィルター	reference/operations.md	_or、_and、_not、eq、contains
トランザクション	reference/operations.md	@transaction、response バインディング
環境設定	reference/config.md	dataconnect.yaml、connector.yaml
リアルタイムサブスクリプション	reference/realtime.md	@refresh、subscribe()、自動更新
Cloud Functions の統合	reference/cloud_functions.md	onMutationExecuted、トリガーイベント
データのシードとマイグレーション	reference/data_seeding.md	seed_data.gql、_insertMany、Admin SDK の一括処理
スターターテンプレート	templates.md	CRUD、ユーザー所有リソース、多対多、SDK の初期化

---

デプロイと CLI

設定について詳しくは、reference/config.md を参照してください。

現在のタスクに応じて、次のパターンに従ってください。

Firebase プロジェクトで SQL Connect を初期化する方法

1. アプリのアイデアを理解します。不明な点があれば、確認の質問をしてください。
2. npx -y firebase-tools@latest init dataconnect を実行します。
3. アプリのテンプレートと生成された SDK がセットアップされていることを確認します。

SQL Connect を使ってローカルでアプリを構築する方法

1. エミュレーターを起動します。 npx -y firebase-tools@latest emulators:start --only dataconnect
2. スキーマとオペレーションを記述します。
3. ローカルのテストデータを seed_data.gql に追加します。 reference/data_seeding.md を参照してください。
4. npx -y firebase-tools@latest dataconnect:compile または npx -y firebase-tools@latest dataconnect:sdk:generate を実行して検証します。
5. アプリでオペレーションを使い、ビルドします。

SQL Connect を Cloud SQL にデプロイする方法

1. npx -y firebase-tools@latest deploy --only dataconnect を実行します。

例

スキーマとオペレーションの完全な動作コード例については、 examples.md を参照してください。

すぐに使えるスターターテンプレート（CRUD、ユーザー所有リソース、多対多、 YAML 設定、SDK の初期化）については、templates.md を参照してください。