pg_graphql 是一款功能强大的 PostgreSQL 插件，它能够在数据库内部直接提供一个完整的 GraphQL 服务引擎。通过该插件，您可以将现有的 SQL 表、视图及其关系自动转换为一个功能完备的 GraphQL Schema，从而实现无服务器（Serverless）的 GraphQL 查询。

它在 PostgreSQL 与 GraphQL 之间搭建了一座无缝的桥梁，使得任何能够连接到数据库的客户端或编程语言都能利用 GraphQL 声明式、强类型的查询优势，而无需部署和维护额外的中间层服务。

适用场景

快速原型开发：在几分钟内为您的数据库提供一个功能齐全的 GraphQL API，加速前端和移动应用的开发。

简化后端架构：对于以数据为中心的应用，可以用 pg_graphql 替代传统的 REST API 或自定义的 GraphQL 服务器，降低架构复杂性。

数据即服务 (Data as a Service)：将数据库作为一项服务，安全地向内部团队或外部合作伙伴暴露结构化的数据查询能力。

与 Serverless 框架集成：在 Vercel、Netlify 或 Supabase 等平台上，与函数计算结合，构建高性能、可扩展的应用。

注意事项

主键要求：所有需要在 GraphQL Schema 中暴露的表都必须定义主键。没有主键的表将被插件忽略，无法通过 GraphQL API 进行查询。

创建与删除插件

创建插件

执行以下 SQL 命令以启用 pg_graphql 插件。

删除插件

如果不再需要，可以执行以下命令将其卸载。

基础使用

以下是一个完整的入门示例：

创建表结构

首先，我们创建 accounts (账户) 和 posts (文章) 两张表，并使用外键建立它们之间的一对多关系。

-- 创建账户表
CREATE TABLE accounts (
id SERIAL PRIMARY KEY,
email TEXT NOT NULL UNIQUE
);

-- 创建文章表，并通过 author_id 关联到 accounts 表
CREATE TABLE posts (
id SERIAL PRIMARY KEY,
author_id INT NOT NULL REFERENCES accounts(id),
title TEXT NOT NULL,
body TEXT
);

插入示例数据

向表中插入一些数据以供后续查询。

-- 插入一个账户
INSERT INTO accounts (email) VALUES ('author@example.com');

-- 为该账户插入两篇文章
INSERT INTO posts (author_id, title, body) VALUES
(1, 'pg_graphql 入门', '这是第一篇文章...'),
(1, 'GraphQL 查询技巧', '这是第二篇文章...');

执行 GraphQL 查询

使用核心函数 graphql.resolve 来执行 GraphQL 查询。查询语句作为文本参数传入。

SELECT graphql.resolve($$
query GetAccountsWithPosts {
accountsCollection {
edges {
node {
id
email
postsCollection {
edges {
node {
title
}
}
}
}
}
}
}
$$);

查看返回结果

graphql.resolve 函数会返回一个 JSONB 对象，其中包含 data 和 errors 两个字段。

{
"data": {
"accountsCollection": {
"edges": [
{
"node": {
"id": 1,
"email": "author@example.com",
"postsCollection": {
"edges": [
{ "node": { "title": "pg_graphql 入门" } },
{ "node": { "title": "GraphQL 查询技巧" } }
]
}
}
}
]
}
}
}

核心函数：graphql.resolve

graphql.resolve 是执行所有 GraphQL 操作的核心函数。

函数签名

query (text): 必需，一个包含 GraphQL 查询、变更或订阅操作的字符串。

variables (jsonb): 可选，一个 JSONB 对象，用于为查询中定义的变量提供值。默认为空对象 ({})。

"operationName" (text): 可选，当 query 字符串包含多个命名操作时，用于指定要执行哪一个。

extensions (jsonb): 可选，用于传递 GraphQL 扩展协议的数据，通常用于高级工具链集成。

调用示例

无变量查询

最简单的调用方式是直接传入 GraphQL 查询字符串。

SELECT graphql.resolve('{ accountsCollection { edges { node { id } } } }');

使用变量

为了提高查询的复用性和安全性，推荐使用变量。

SELECT graphql.resolve(
'query GetAccountById($id: Int!) {
accountsCollection(filter: { id: { eq: $id } }) {
edges {
node {
email
}
}
}
}',
'{"id": 1}'
);

指定操作名称

如果一个请求中包含多个操作，需要通过 "operationName" 参数来指定要执行哪一个。

SELECT graphql.resolve(
$$
query GetAccounts { accountsCollection { edges { node { id } } } }
query GetPosts { postsCollection { edges { node { title } } } }
$$,
'{}',
'GetPosts' -- 指定执行 GetPosts 操作
);

AI 原生 BaaS 平台 Supabase 版