Firebase Data Connect 提供了多种与 Cloud SQL 数据库交互的方式：
- 原生 GraphQL：在
schema.gql中定义类型，Data Connect 会将您的 GraphQL 操作转换为 SQL。这是标准方法，可提供强类型和架构强制结构。本页之外的大部分 Data Connect文档都讨论了此 选项。在可能的情况下，您应使用此方法来充分利用完整的类型安全性和工具支持。 - **
@view指令** ：在schema.gql中定义由 自定义SELECTSQL 语句支持的 GraphQL 类型。这对于基于复杂的 SQL 逻辑创建只读的强类型视图非常有用。这些类型可像常规类型一样进行查询。 请参阅@view。 - 原生 SQL：使用特殊根字段将 SQL 语句直接嵌入到 `gql` 文件中的命名
操作中。使用特殊根字段的
gql文件。与 GraphQL 和 `@view` 指令不同，原生 SQL 不提供强类型输出。Unlike GraphQL and the@viewdirective, native SQL doesn't provide strongly-typed output.
本指南重点介绍原生 SQL 选项。
原生 SQL 的常见用例
虽然原生 GraphQL 提供完整的类型安全性，并且 @view 指令为只读 SQL 报告提供强类型结果，但原生 SQL 提供了以下所需的灵活性：
- PostgreSQL 扩展程序：直接查询和使用任何已安装的 PostgreSQL
扩展程序（例如用于地理空间数据的
PostGIS），而无需在 GraphQL 架构中映射复杂 类型。 - 复杂查询：执行包含联接、子查询、 聚合、窗口函数和存储过程的复杂 SQL。
- 数据操纵 (DML)：直接执行
INSERT, UPDATE, DELETE操作 。（不过，请勿将原生 SQL 用于数据定义语言 (DDL) 命令。您必须继续使用 GraphQL 进行架构级更改，以使后端和生成的 SDK 保持同步。） - 数据库特定功能：利用 PostgreSQL 特有的函数、运算符或数据类型 。
- 性能优化：手动调整关键路径的 SQL 语句。
原生 SQL 根字段
如需使用 SQL 编写操作，请使用 query 或 mutation 类型的以下根字段之一：
query 字段
| 字段 | 说明 |
|---|---|
_select |
执行 SQL 查询，返回零行或多行。 实参：
返回：JSON 数组 ( |
_selectFirst |
执行预期返回零行或一行的 SQL 查询。 实参：
返回：JSON 对象 ( |
mutation 字段
| 字段 | 说明 |
|---|---|
_execute |
执行 DML 语句 ( 实参：
返回： 结果中会忽略 |
_executeReturning |
执行带有 实参：
返回：JSON 数组 ( |
_executeReturningFirst |
执行带有 实参：
返回：JSON 对象 ( |
备注：
操作是使用授予 Data Connect 服务账号的权限执行的。
如果您使用
@table指令 (@table(name: "ExampleTable"))显式设置表名称，则还必须在 SQL 语句中将表名称用 引号括起来 (SELECT field FROM "ExampleTable" ...)。如果没有引号，Data Connect 会将表 名称转换为蛇形命名法 (
example_table)。
语法规则和限制
原生 SQL 会强制执行严格的解析规则，以确保安全性并防止 SQL 注入。请注意以下限制：
- 注释：使用块注释 (
/* ... */)。禁止使用行注释 (--)，因为它们可能会在查询串联期间截断后续子句（例如安全过滤条件）。 - 参数：使用与
params数组顺序匹配的位置参数（$1、$2）。不支持命名参数（$id、:name）。 - 字符串：支持扩展字符串字面量 (
E'...') 和美元引号字符串 ($$...$$)。不支持 PostgreSQL Unicode 转义 (U&'...')。
注释中的参数
解析器会忽略块注释中的所有内容。如果您注释掉包含参数的行（例如 /* WHERE id = $1 */），则还必须从 params 列表中移除该参数，否则操作将失败并显示错误 unused parameter: $1。
示例
示例 1：带有字段别名的基本 SELECT
您可以为根字段设置别名（例如 movies: _select），使客户端响应更简洁（data.movies 而不是 data._select）。
queries.gql：
query GetMoviesByGenre($genre: String!, $limit:Int!) @auth(level: PUBLIC) {
movies: _select(
sql: """
SELECT id, title, release_year, rating
FROM movie
WHERE genre = $1
ORDER BY release_year DESC
LIMIT $2
""",
params: [$genre, $limit]
)
}
使用客户端 SDK 运行查询后，结果将位于 data.movies 中。
示例 2：基本 UPDATE
mutations.gql：
mutation UpdateMovieRating($movieId: UUID!, $newRating: Float!) @auth(level: NO_ACCESS) {
_execute(
sql: """
UPDATE movie
SET rating = $2
WHERE id = $1
""",
params: [$movieId, $newRating]
)
}
使用客户端 SDK 运行变更后，受影响的行数将位于 data._execute 中。
示例 3：基本聚合
queries.gql：
query GetTotalReviewCount @auth(level: PUBLIC) {
stats: _selectFirst(
sql: "SELECT COUNT(*) as total_reviews FROM \"Reviews\""
)
}
使用客户端 SDK 运行查询后，结果将位于 data.stats.total_reviews 中。
示例 4：带有 RANK 的高级汇总
queries.gql：
query GetMoviesRankedByRating @auth(level: PUBLIC) {
_select(
sql: """
SELECT
id,
title,
rating,
RANK() OVER (ORDER BY rating DESC) as rank
FROM movie
WHERE rating IS NOT NULL
LIMIT 20
""",
params: []
)
}
使用客户端 SDK 运行查询后，结果将位于 data._select 中。
示例 5：带有 RETURNING 和身份验证上下文的 UPDATE
mutations.gql：
mutation UpdateMyReviewText($movieId: UUID!, $newText: String!) @auth(level: USER) {
updatedReview: _executeReturningFirst(
sql: """
UPDATE "Reviews"
SET review_text = $2
WHERE movie_id = $1 AND user_id = $3
RETURNING movie_id, user_id, rating, review_text
""",
params: [$movieId,$newText,{_expr: "auth.uid" }]
)
}
使用客户端 SDK 运行变更后，更新后的帖子数据将位于 data.updatedReview 中。
示例 6：带有 upsert（原子获取或创建）的高级 CTE
此模式有助于确保在插入子记录（例如评论）之前存在依赖记录（例如用户或电影），所有这些都在单个数据库事务中完成。
mutations.gql：
mutation CreateMovieCTE($movieId: UUID!, $userId: UUID!, $reviewId: UUID!) {
_execute(
sql: """
WITH
new_user AS (
INSERT INTO "user" (id, username)
VALUES ($2, 'Auto-Generated User')
ON CONFLICT (id) DO NOTHING
RETURNING id
),
movie AS (
INSERT INTO movie (id, title, image_url, release_year, genre)
VALUES ($1, 'Auto-Generated Movie', 'https://placeholder.com', 2025, 'Sci-Fi')
ON CONFLICT (id) DO NOTHING
RETURNING id
)
INSERT INTO "Reviews" (id, movie_id, user_id, rating, review_text, review_date)
VALUES (
$3,
$1,
$2,
5,
'Good!',
NOW()
)
""",
params: [$movieId, $userId, $reviewId]
)
}
示例 7：使用 Postgres 扩展程序
借助原生 SQL，您可以使用 Postgres 扩展程序（例如 PostGIS），而无需将复杂的几何图形类型映射到 GraphQL 架构中或更改底层表。
在此示例中，假设您的餐厅应用有一个表，该表在元数据 JSON 列中存储位置
数据（例如 {"latitude": 37.3688, "longitude": -122.0363}）。
如果您已启用 PostGIS 扩展程序，
则可以使用标准 Postgres JSON 运算符 (->>) 动态提取这些值，并将它们传递给 PostGIS ST_MakePoint 函数。
query GetNearbyActiveRestaurants($userLong: Float!, $userLat: Float!, $maxDistanceMeters: Float!) @auth(level: USER) {
nearby: _select(
sql: """
SELECT
id,
name,
tags,
ST_Distance(
ST_MakePoint((metadata->>'longitude')::float, (metadata->>'latitude')::float)::geography,
ST_MakePoint($1, $2)::geography
) as distance_meters
FROM restaurant
WHERE active = true
AND metadata ? 'longitude' AND metadata ? 'latitude'
AND ST_DWithin(
ST_MakePoint((metadata->>'longitude')::float, (metadata->>'latitude')::float)::geography,
ST_MakePoint($1, $2)::geography,
$3
)
ORDER BY distance_meters ASC
LIMIT 10
""",
params: [$userLong, $userLat, $maxDistanceMeters]
)
}
使用客户端 SDK 运行查询后，结果将位于 data.nearby 中。
安全最佳实践：动态 SQL 和存储过程
Data Connect 会在 GraphQL 到数据库边界安全地对所有输入进行参数化，从而全面保护您的标准 SQL 查询 免受一级 SQL 注入的攻击。不过，如果您使用 SQL 调用执行动态 SQL 的自定义 Postgres 存储过程或函数，则必须确保内部 PL/pgSQL 代码安全地处理这些参数。
如果存储过程直接将用户输入连接到 EXECUTE 字符串中，则会绕过参数化并创建二级 SQL 注入漏洞：
-- INSECURE: Do not concatenate parameters into dynamic strings!
CREATE OR REPLACE PROCEDURE unsafe_update(user_input TEXT)
LANGUAGE plpgsql AS $$
BEGIN
-- A malicious user_input (e.g., "val'; DROP TABLE users; --") will execute as code.
EXECUTE 'UPDATE target_table SET status = ''' || user_input || '''';
END;
$$;
为避免这种情况，请遵循以下最佳实践：
- 使用
USING子句：在存储过程中编写动态 SQL 时，请务必使用USING子句安全地绑定数据参数。 - 对标识符使用
format()：对安全数据库标识符注入（例如表名称）使用带有%I标志的format()。 - 严格允许标识符：请勿让客户端应用随意选择数据库标识符。如果您的过程需要动态标识符，请在执行之前针对 PL/pgSQL 逻辑中的硬编码允许列表验证输入。
-- SECURE: Use format() for identifiers and USING for data values
CREATE OR REPLACE PROCEDURE secure_update(target_table TEXT, new_value TEXT, row_id INT)
LANGUAGE plpgsql AS $$
BEGIN
-- Validate the dynamic table name against an allowlist
IF target_table NOT IN ('orders', 'users', 'inventory') THEN
RAISE EXCEPTION 'Invalid table name';
END IF;
-- Execute securely
EXECUTE format('UPDATE %I SET status = $1 WHERE id = $2', target_table)
USING new_value, row_id;
END;
$$;