使用原生 SQL 实现 Firebase SQL Connect 操作

本指南介绍如何使用 SQL 而不是 GraphQL 编写 Firebase SQL Connect 操作。page_type: guideannouncement: >Native SQL is available as a feature Preview, which means that it isn'tsubject to any SLA or deprecation policy and could change inbackwards-incompatible ways.如果您将此功能与执行动态 SQL 的存储过程 或函数搭配使用，请遵循本页底部说明的安全最佳实践 。

Firebase SQL Connect 提供了多种与 Cloud SQL 数据库交互的方式：

• 原生 GraphQL：在 schema.gql 中定义类型， SQL Connect 会将您的 GraphQL 操作转换为 SQL。这是标准方法，可提供强类型和架构强制结构。本页之外的大部分 SQL Connect 文档都讨论了此选项。在可能的情况下，您应使用此方法来充分利用完整的类型安全性和工具支持。
• **@view 指令** ：在 schema.gql 中定义由 自定义 SELECT SQL 语句支持的 GraphQL 类型。这对于基于复杂的 SQL 逻辑创建只读的强类型视图非常有用。这些类型可以像常规类型一样进行查询。 请参阅 @view。
• 原生 SQL：使用特殊根字段将 SQL 语句直接嵌入到 .gql 文件中的命名操作中。这提供了最大的灵活性和直接控制，尤其适用于标准 GraphQL 不支持的操作、利用数据库特定功能或利用 PostgreSQL 扩展程序的操作。 与 GraphQL 和 @view 指令不同，原生 SQL 不提供强类型输出。

本指南重点介绍原生 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 查询，返回零行或多行。 实参： sql：SQL 语句字符串字面量。为防止 SQL 注入，请对形参值使用位置占位符（$1、 $2 等）。 params：要绑定到 占位符的有序值列表。这可以包括字面量、GraphQL 变量和 特殊的服务器注入上下文映射，例如 {_expr: "auth.uid"}（经过身份验证的用户的 ID）。 返回：JSON 数组 ([Any])。
_selectFirst	执行预期返回零行或一行的 SQL 查询。 实参： sql：SQL 语句字符串字面量。为防止 SQL 注入，请对形参值使用位置占位符（$1、 $2 等）。 params：要绑定到 占位符的有序值列表。这可以包括字面量、GraphQL 变量和 特殊的服务器注入上下文映射，例如 {_expr: "auth.uid"}（经过身份验证的用户的 ID）。 返回：JSON 对象 (Any) 或 null。

mutation 字段

字段	说明
_execute	执行 DML 语句 (INSERT, UPDATE, DELETE)。 实参： sql：SQL 语句字符串字面量。为防止 SQL 注入，请对形参值使用位置占位符（$1、$2 等）。 您可以在此处使用数据修改型通用表表达式（例如 WITH new_row AS (INSERT...)）因为此字段仅返回行数。只有 _execute 支持 CTE。 params：要绑定到 占位符的有序值列表。这可以包括字面量、GraphQL 变量和 特殊的服务器注入上下文映射，例如 {_expr: "auth.uid"}（经过身份验证的用户的 ID）。 返回：Int（受影响的行数 ）。 结果中会忽略 RETURNING 子句。
_executeReturning	执行带有 RETURNING 子句的 DML 语句，返回零行或多行。 实参： sql：SQL 语句字符串字面量。为防止 SQL 注入，请对形参值使用位置占位符（$1、$2 等）。不支持数据修改型 通用表表达式。 params：要绑定到 占位符的有序值列表。这可以包括字面量、GraphQL 变量和 特殊的服务器注入上下文映射，例如 {_expr: "auth.uid"}（经过身份验证的用户的 ID）。 返回：JSON 数组 ([Any])。
_executeReturningFirst	执行带有 RETURNING 子句的 DML 语句， 预期返回零行或一行。 实参： sql：SQL 语句字符串字面量。为防止 SQL 注入，请对形参值使用位置占位符（$1、$2 等）。不支持数据修改型 通用表表达式。 params：要绑定到 占位符的有序值列表。这可以包括字面量、GraphQL 变量和 特殊的服务器注入上下文映射，例如 {_expr: "auth.uid"}（经过身份验证的用户的 ID）。 返回：JSON 对象 (Any) 或 null。

备注：

• 操作是使用授予 SQL Connect服务账号的权限执行的。

语法规则和限制

原生 SQL 会强制执行严格的解析规则，以确保安全并防止 SQL 注入。请注意以下限制：

• 注释：使用块注释 (/* ... */)。禁止使用行注释 (--)，因为它们可能会在查询串联期间截断后续子句（例如安全过滤条件）。
• 形参：使用与 params数组顺序匹配的位置形参（$1、$2）。不支持命名形参（$id、:name）。
• 字符串：支持扩展字符串字面量 (E'...') 和美元引号字符串 ($$...$$)。不支持 PostgreSQL Unicode 转义 (U&'...')。

注释中的形参

解析器会忽略块注释内的所有内容。如果您注释掉包含形参的行（例如 /* WHERE id = $1 */），您还必须从 params 列表中移除该形参，否则操作将失败并显示错误 unused parameter: $1。

命名规则

编写原生 SQL 时，您将直接与 PostgreSQL 数据库交互，因此必须对表和列使用实际的数据库名称。默认情况下，SQL Connect 会自动将 GraphQL 架构中的名称映射到数据库中的蛇形命名法 ，除非您使用 @table(name) 和 @col(name) 指令显式自定义 Postgres 标识符。

如果您定义不带指令的类型，GraphQL 表和字段名称将映射到默认的 snake_case Postgres 标识符：

schema.gql	queries.gql
type UserProfile { userId: ID! displayName: String }	query GetUserProfileDefault($id: ID!) { profile: _selectFirst( sql: """ SELECT user_id, display_name FROM user_profile WHERE user_id = $1 """, params: [$id] ) }

默认情况下，PostgreSQL 标识符不区分大小写。如果您使用 @table 或 @col 等指令来指定包含大写字母或大小写混合字母的名称，则必须 在 SQL 语句中将该标识符用双引号括起来。

在以下示例中，您必须对表名称使用 "UserProfiles"，对 "profileId"列使用 userId。displayName 字段遵循默认转换为 display_name：

schema.gql	queries.gql
type UserProfileCustom @table(name: "UserProfiles") { userId: ID! @col(name: "profileId") displayName: String }	query GetUserProfileCustom($id: ID!) { profile: _selectFirst( sql: """ SELECT "profileId", display_name FROM "UserProfiles" WHERE "profileId" = $1 """, params: [$id] ) }

用法示例

示例 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 和 Auth Context 的 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!) @auth(level: USER) {
  _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]
  )
}

重要提示： 数据修改型 CTE（在 WITH子句中使用 INSERT、UPDATE 或 DELETE）**仅受** _execute 支持。

_executeReturning 和 _executeReturningFirst 会将您的查询封装在 父 CTE 中，以将输出格式设置为 JSON。PostgreSQL 不允许将数据修改型 CTE 嵌套在另一个数据修改型语句中，这会导致查询失败。

示例 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 和存储过程

SQL 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;
$$;