5 分钟跑通 PostgREST：从一张表到第一个 PostgreSQL REST API

5 分钟跑通 PostgREST：从一张表到第一个 PostgreSQL REST API

【免费下载链接】postgrestREST API for any Postgres database项目地址: https://gitcode.com/GitHub_Trending/po/postgrest

你手边已经有一个 PostgreSQL 库，想立刻把它变成对外暴露的 REST API？PostgREST 就是干这个的：把表直接映射成端点，权限交给数据库角色，过滤写在 URL 查询参数里，一行后端代码都不用写。

选对姿势装 PostgREST，十分钟都不用

先说结论：装 PostgREST 这件事本身没有门槛，三种姿势按场景选就行。

macOS 上brew install postgrest，一行搞定，适合本地开发；Linux 上pacman -S postgrest或apt install postgrest，适合你不想碰容器、直接跑在机器上的场景；想要环境完全一致，就一行命令拉起 PostgREST 容器：

docker run --rm --net=host -p 3000:3000 \ -e PGRST_DB_URI="postgres://app_user:password@localhost/postgres" \ postgrest/postgrest

⚠️ 生产环境建议 Docker：镜像极小，环境一致，坏了一眼就能看出来。

最小可运行配置：只写四个参数

装好之后，先别急着看全部配置项。让 PostgREST 活过来，只需要四个参数：

# postgrest.conf db-uri = "postgres://authenticator:mysecret@localhost:5432/postgres" db-schemas = "api" db-anon-role = "web_anon" server-port = 3000

db-uri是连接串，里面这个角色必须是后面会讲的认证器；db-schemas告诉 PostgREST 暴露哪个 schema；db-anon-role是匿名请求用的角色。端口不写默认就是 3000，连接池默认 10，够起步用了。

postgrest postgrest.conf

看到API server listening on port 3000就说明它活了。另开一个终端验证：

curl http://localhost:3000/

返回一个空的 JSON 对象{}，没报 500，链路就通了。

三个角色看懂 PostgREST 安全模型

理解 PostgREST 的权限，记住一条链路就够了：

打个比方：authenticator 就像前台，每个进来的请求先由它接电话；带着 JWT 的，它转给令牌里声明的那个人；没带令牌的，一律转给接待处 web_anon。至于对方能碰哪些表，全看数据库里怎么授权，跟 PostgREST 本身无关。这就是"安全交给数据库"的含义。

三个角色建起来其实就五行：

create role authenticator login noinherit password 'mysecret'; create role web_anon nologin; create role web_user nologin; grant web_anon, web_user to authenticator;

端到端实战：建张 todos 表，curl 把它摸一遍

下面是一个完整的故事线：建表、授权、起服务，然后对/todos做一轮增删改查。

先建表，这是 API 的第一个端点：

create schema api; create table api.todos ( id int generated by default as identity primary key, task text not null, done boolean not null default false, due timestamptz ); insert into api.todos (task) values ('跑通 PostgREST');

再给匿名角色开权限：

grant usage on schema api to web_anon; grant select on api.todos to web_anon;

配置文件换成上面那四个参数，db-schemas填api。启动后，开测：

curl "http://localhost:3000/todos"

你应看到：一行 JSON 数组，跑通 PostgREST那条就在里面，响应头里还有Content-Range。

curl -X POST http://localhost:3000/todos \ -H "Content-Type: application/json" \ -d '{"task":"再写条"}'

你应看到：201 加上新记录，id 是数据库自动生成的。

curl -X PATCH "http://localhost:3000/todos?done=is.false" \ -d '{"done":true}'

你应看到：204 无内容，之前那条被标记完成了。

curl -X DELETE "http://localhost:3000/todos?done=is.false"

你应看到：204，记录没了。

顺手测一下过滤和排序，这是 PostgREST 日常最好用的部分：

curl "http://localhost:3000/todos?done=is.true&select=task,due&order=due.asc"

只回传你select里的列，按due升序。要是忘了建表就请求/todos，会得到 404；拿只读角色去 POST，会得到 401 加一句permission denied——这两条报错，是这套权限模型在正常工作的证明。

上生产前：六项加固清单

1. 给需要按用户隔离的表启用行级安全：alter table api.todos enable row level security;然后写策略。
2. 连接池按并发调：db-pool = 20，默认 10，不够就加，别盲目拉满。
3. JWT 密钥定期换；容器里用jwt-secret-is-base64 = true喂 base64 密钥，比裸字符串好管理。
4. 跨域来源收紧：server-cors-allowed-origins = "https://your-frontend.example"，别用默认的全放行。
5. 日志降档：本地log-level = "debug"，生产error，别把 debug 留在生产。
6. 兜底行数限制：db-max-rows = 1000加max-affected，防手滑触发万行级的大查询。

完整参数在 docs/references/configuration.rst 里，按需查就行，不用背。

避坑速查：现象 → 原因 → 解法

两个提醒：改完数据库里的权限和结构，PostgREST 要重载才生效；Docker 部署时优先用PGRST_前缀的环境变量，比如PGRST_DB_URI，不用挂载配置文件。

下一步往哪走

跑通之后，自然的下一步是看/路径返回的 OpenAPI 文档——你的 API 长什么样，它自己会说；再往后是多 schema 隔离和 RLS 的多租户进阶。完整配置参考见 docs/references/configuration.rst，官方教程从 docs/tutorials/tut0.rst 开始。

【免费下载链接】postgrestREST API for any Postgres database项目地址: https://gitcode.com/GitHub_Trending/po/postgrest