Firebase SQL Connect

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

[!NOTE] 製品名の変更: Firebase Data Connect は Firebase SQL Connect にリネームされました。このスキルリポジトリ内の「Data Connect」または「Firebase Data Connect」を指すすべての説明、参照、および例は、「SQL Connect」および「Firebase SQL Connect」にも適用されます。

プロジェクト構造

dataconnect/
├── dataconnect.yaml      # Service configuration
├── 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 vs. ネイティブ 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, 一対多、多対多)
• データ型 (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 を読んでください:

• @auth(level: ...) (PUBLIC、USER、NO_ACCESS)。
• @check と @redact (行レベルセキュリティと検証)。

リアルタイムサブスクリプションについて reference/realtime.md を読んでください:

• 時間ベースのポーリングとイベント駆動型更新用の @refresh ディレクティブ。
• 更新トリガーを正確にスコープするための CEL 条件。

ネイティブ 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"

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/advanced.md	Vector, @col(dataType: "vector")
フルテキスト検索	reference/advanced.md	@searchable
データのアップサート	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(), 自動更新
スターターテンプレート	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. npx -y firebase-tools@latest dataconnect:compile または npx -y firebase-tools@latest dataconnect:sdk:generate を実行して 検証します。
4. アプリで操作を使用してビルドします。

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

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

例

スキーマと操作の完全で動作するコード例については、 examples.md を参照してください。

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