PostgREST 安装部署快速上手零代码把 PostgreSQL 变成 RESTful API【免费下载链接】postgrestREST API for any Postgres database项目地址: https://gitcode.com/GitHub_Trending/po/postgrestPostgREST 是一个运行在你 PostgreSQL 数据库前面的守门人你不用写任何 Controller、路由或 ORM 代码它就能把数据库里的表、视图和函数直接暴露成标准的 RESTful API。查询条件、分页、排序、字段筛选、关联嵌入全部通过 URL 查询参数表达而权限控制则完全交给 PostgreSQL 的角色和行级安全策略。换句话说PostgREST 安装完成后你的数据库本身就是一台 API 服务器。动手前你需要准备什么这一节帮你把要不要装、装哪种、数据库要会什么一次性想清楚避免装到一半才发现环境不对。运行环境PostgreSQL 14 就够了PostgREST 只要求一个条件一个支持中的 PostgreSQL 数据库官方支持 14 及以上版本。PostgREST 自身是单进程编译几乎不需要系统依赖这也是它部署轻量的根本原因。对数据库的三点最小认知你不需要是 PostgreSQL 专家但跑通 PostgREST 需要理解这三件事角色rolePostgREST 用数据库角色代表谁来访问 API后面会细讲模式schema表、视图、函数都挂在某个 schema 下PostgREST 只暴露你指定的 schema授权GRANTAPI 能做什么完全由数据库里的GRANT语句决定——没有授权就没有接口。三种部署路径快速选型部署方式适合场景特点一句话建议包管理器brew / pacman / choco 等本地开发、临时试用装完即用依赖自动处理版本可能略旧想最快看到效果选它静态二进制文件生产服务器、版本精确控制跨 Linux 发行版直接运行无运行时依赖可锁定版本生产环境首选Docker 容器postgrest/postgrest容器化、云原生、与 Postgres 一起编排官方镜像基于 scratch 构建只有静态二进制体积约 14MB配置走PGRST_环境变量已用 Docker 跑 Postgres 的团队直接用三种方式装出来的都是同一个程序差异只在怎么拿到可执行文件。验证是否装好统一执行postgrest --help看到用法输出即成功。最快跑通第一个 PostgREST API从建表到 curl 验证 CRUD这是全文的主线照着敲完你就拥有了一个能增删改查的 API。以一张todos表为例。第 1 步建表和数据库角色-- 表放在 api 模式下稍后只暴露这个模式 CREATE SCHEMA api; CREATE TABLE api.todos ( id serial PRIMARY KEY, task text NOT NULL, done boolean DEFAULT false ); INSERT INTO api.todos (task) VALUES (学习 PostgREST), (跑通第一个 API); -- 匿名角色未携带 JWT 的请求用它执行 CREATE ROLE anon NOLOGIN; GRANT USAGE ON SCHEMA api TO anon; GRANT SELECT ON api.todos TO anon; GRANT USAGE ON SEQUENCE api.todos_id_seq TO anon; -- 认证器角色PostgREST 用它连接数据库再变身成其他角色 CREATE ROLE authenticator LOGIN NOINHERIT PASSWORD secret_password; GRANT anon TO authenticator;注意这里的角色设计已经体现了 PostgREST 的权限思想匿名用户默认只给了SELECT和序列使用权——想让匿名请求能 POST才需要再GRANT INSERT。表结构决定了 API 端点长什么样比如带外键的关联表可以被select参数直接嵌入原理可以看官方文档里的 ER 示例第 2 步写配置文件新建postgrest.conf跑通最小闭环只需要四项db-uri postgres://authenticator:secret_passwordlocalhost:5432/mydb db-schemas api db-anon-role anon jwt-secret reallyreallyreallyreallyverysafe # 至少 32 字符db-uri里的用户就是认证器角色不是普通的数据库账号db-schemas决定哪些 schema 会变成 API 端点db-anon-role缺省时匿名请求会被拒绝jwt-secret缺省时无法验证带 JWT 的请求。完整参数语义可参考 docs/references/configuration.rst也可以执行postgrest -e生成一份带注释的样例配置。第 3 步启动服务postgrest postgrest.conf # 看到类似 Starting PostgREST 的启动日志即成功Docker 方式则通过环境变量传入同样的配置docker run -p 3000:3000 \ -e PGRST_DB_URIpostgres://authenticator:secret_passworddb:5432/mydb \ -e PGRST_DB_SCHEMASapi \ -e PGRST_DB_ANON_ROLEanon \ -e PGRST_JWT_SECRETreallyreallyreallyreallyverysafe \ postgrest/postgrest第 4 步用 curl 验证 CRUD# 读拿到全部待办 curl http://localhost:3000/todos # 条件过滤 字段选择 排序 curl http://localhost:3000/todos?doneis.falseselectid,taskorderid.desc # 写创建一条匿名角色无 INSERT 权限会返回 401/403——这是预期的 curl -X POST http://localhost:3000/todos \ -H Content-Type: application/json \ -d {task: 写文档}如果你给anon补上GRANT INSERT ON api.todos TO anon再发一次 POST 就会返回 201 和新记录——改一行 GRANTAPI 能力就变了这就是 PostgREST 与自研 API 最大的不同。更新与删除同样走查询参数定位行curl -X PATCH http://localhost:3000/todos?ideq.2 \ -H Content-Type: application/json -d {done: true} curl -X DELETE http://localhost:3000/todos?ideq.3访问根路径http://localhost:3000/还能拿到自动生成的 OpenAPI 文档客户端代码可以直接基于它生成。PostgREST 权限模型三类角色如何把安全交给数据库这一节解释一个请求从进来到落地身份是怎么被确认和降权的理解它你就不会在权限配置上踩坑。请求鉴权链路三类角色各就各位角色职责关键约束认证器db-uri中的用户唯一与数据库建立连接的角色随后SET ROLE变身必须NOINHERIT且只能被 GRANT 到它允许扮演的角色匿名角色db-anon-role承接所有未携带 JWT 的请求建议只给只读权限甚至可以不设置直接封死匿名访问用户角色JWT 中的role声明每个真实用户的身份必须 NOLOGIN只能被认证器变出来权限按最小化授予PostgREST 把 JWT 的role声明与数据库角色名对应起来所以签发令牌时 payload 里写role: todo_user请求进来后数据库里执行的就是SET ROLE todo_user。用在线 JWT 工具对照 secret 签发、验签的过程如下HS256 对称签名两层防线表级授权 行级安全最小权限按角色精确GRANT例如匿名用户只能SELECT公开表管理角色才能触碰敏感表。API 的行为上限 角色的权限上限。RLS行级安全表级授权管能不能碰这张表RLS 管能看到哪些行。开启 RLS 后策略里可以直接读取 PostgREST 注入的request.jwt.claims把user_id与 JWT 声明比对实现每个用户只看到自己的数据。官方对这两层机制有专门讲解见 docs/explanations/db_authz.rst。配置项按目的归类速查完整参数文档很长这里按你想解决什么问题分成四组只列最常用的。所有参数都可用PGRST_前缀的同名环境变量覆盖如db-pool对应PGRST_DB_POOL。连接与连接池参数类型默认值说明示例db-uriStringpostgresql://PostgreSQL 连接串用户即认证器角色postgres://auth:passdb:5432/appdb-poolInt10连接池最大连接数不可热重载20db-pool-acquisition-timeoutInt10请求等待空闲连接的上限秒30db-pool-max-lifetimeInt1800池中连接最大存活时间秒3600db-pool-automatic-recoveryBooleantrue连接断开后是否自动重连false安全与认证参数类型默认值说明示例db-schemasStringpublic暴露为 API 端点的 schema 列表api, v1db-anon-roleString无匿名请求使用的角色不设置则拒绝匿名anonjwt-secretString无JWT 验签密钥必须 ≥32 字符文件名可从文件读取./secrets/jwt.txtjwt-secret-is-base64Booleanfalse密钥是否按 base64 解码truejwt-role-claim-keyString$.role从 JWT 哪个声明提取角色名$.https://app/rolejwt-audString无额外校验 JWT 的aud声明api-v1服务器与网络参数类型默认值说明示例server-portInt3000监听端口0表示自动分配8080server-hostString!4绑定地址127.0.0.1server-cors-allowed-originsString无CORS 白名单不设置 放行所有来源https://myapp.comserver-timing-enabledBooleanfalse返回 Server-Timing 头便于排障trueadmin-server-portInt无独立管理端口健康检查、metrics3001高级与 OpenAPI参数类型默认值说明示例db-max-rowsInt无限制单次查询最大返回行数防大结果集打爆内存1000db-aggregates-enabledBooleanfalse允许selectcount(*)等聚合truedb-plan-enabledBooleanfalse允许通过 Accept 头请求执行计划truedb-pre-requestString无每个请求执行前调用的钩子函数审计、限流api.hook_pre_requestopenapi-modeStringfollow-privilegesOpenAPI 文档按调用者权限裁剪 / 忽略权限 / 禁用disabledclient-error-verbosityStringverbose返回给客户端的错误细节程度minimallog-levelStringerror日志级别crit/error/warn/info/debuginfo两个容易忽略的点配置支持热重载发送SIGUSR2或在数据库里NOTIFY pgrst, reload config改完配置不用重启如果数据库前面挂了 PgBouncer 的 transaction pooling 模式要把db-prepared-statements和db-channel-enabled都设为false。上生产前的 PostgREST 部署自检清单发布前逐项过一遍能挡掉绝大多数线上事故。连接与容量db-pool与数据库max_connections匹配多实例部署时总池量不超限设置了db-max-rows避免select*一次拉回百万行数据库在高并发下连接打满时db-pool-acquisition-timeout有合理值客户端能看到 503 而不是无限挂起认证与密钥jwt-secret至少 32 字符且通过环境变量或文件注入不要写进配置文件再提交到版本库确认db-anon-role的权限是确实需要的最小集匿名能写数据的大多是配置失误多环境共享签发方时配置了jwt-aud防止 A 环境的 token 打到 B 环境涉及多租户或私有数据时关键表已开启 RLS并且策略读取的是 JWT claims 而不是可伪造的请求头网络与输出server-cors-allowed-origins已显式配置默认放行所有来源是常见漏配openapi-mode明确取值对外 API 建议disabled或follow-privileges避免信息暴露client-error-verbosity minimal防止数据库内部细节经错误信息泄露log-level info起步配合admin-server-port暴露健康检查行为验证故意用错误/过期/伪造签名的 JWT 请求一次确认返回 401 而不是 200访问未授权端点确认返回 404/403修改配置后执行热重载killall -SIGUSR2 postgrest确认新配置生效用db-pre-request钩子或数据库审计表抽查一条写操作确认身份链路认证器 → 目标角色符合预期下一步学什么跑通 CRUD 只是起点PostgREST 的天花板由你的数据库设计决定关联嵌入查询利用外键在 URL 里嵌套查询关联表select*,films(*)把多表 JOIN 变成一次请求详见 docs/references/api/resource_embedding.rstRPC 与钩子函数把复杂业务逻辑写成数据库函数暴露为 RPC 端点配合db-pre-request做审计和限流部署运维进阶多实例负载均衡、PgBouncer 外部连接池、只读副本与零停机配置更新可参考 docs/explanations/architecture.rst 了解请求在各组件间的流转。把权限设计好、把 schema 划分清楚PostgREST 就会持续替你把数据库翻译成一套稳定、自描述的 REST API。【免费下载链接】postgrestREST API for any Postgres database项目地址: https://gitcode.com/GitHub_Trending/po/postgrest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PostgREST 安装部署快速上手：零代码把 PostgreSQL 变成 RESTful API
PostgREST 安装部署快速上手零代码把 PostgreSQL 变成 RESTful API【免费下载链接】postgrestREST API for any Postgres database项目地址: https://gitcode.com/GitHub_Trending/po/postgrestPostgREST 是一个运行在你 PostgreSQL 数据库前面的守门人你不用写任何 Controller、路由或 ORM 代码它就能把数据库里的表、视图和函数直接暴露成标准的 RESTful API。查询条件、分页、排序、字段筛选、关联嵌入全部通过 URL 查询参数表达而权限控制则完全交给 PostgreSQL 的角色和行级安全策略。换句话说PostgREST 安装完成后你的数据库本身就是一台 API 服务器。动手前你需要准备什么这一节帮你把要不要装、装哪种、数据库要会什么一次性想清楚避免装到一半才发现环境不对。运行环境PostgreSQL 14 就够了PostgREST 只要求一个条件一个支持中的 PostgreSQL 数据库官方支持 14 及以上版本。PostgREST 自身是单进程编译几乎不需要系统依赖这也是它部署轻量的根本原因。对数据库的三点最小认知你不需要是 PostgreSQL 专家但跑通 PostgREST 需要理解这三件事角色rolePostgREST 用数据库角色代表谁来访问 API后面会细讲模式schema表、视图、函数都挂在某个 schema 下PostgREST 只暴露你指定的 schema授权GRANTAPI 能做什么完全由数据库里的GRANT语句决定——没有授权就没有接口。三种部署路径快速选型部署方式适合场景特点一句话建议包管理器brew / pacman / choco 等本地开发、临时试用装完即用依赖自动处理版本可能略旧想最快看到效果选它静态二进制文件生产服务器、版本精确控制跨 Linux 发行版直接运行无运行时依赖可锁定版本生产环境首选Docker 容器postgrest/postgrest容器化、云原生、与 Postgres 一起编排官方镜像基于 scratch 构建只有静态二进制体积约 14MB配置走PGRST_环境变量已用 Docker 跑 Postgres 的团队直接用三种方式装出来的都是同一个程序差异只在怎么拿到可执行文件。验证是否装好统一执行postgrest --help看到用法输出即成功。最快跑通第一个 PostgREST API从建表到 curl 验证 CRUD这是全文的主线照着敲完你就拥有了一个能增删改查的 API。以一张todos表为例。第 1 步建表和数据库角色-- 表放在 api 模式下稍后只暴露这个模式 CREATE SCHEMA api; CREATE TABLE api.todos ( id serial PRIMARY KEY, task text NOT NULL, done boolean DEFAULT false ); INSERT INTO api.todos (task) VALUES (学习 PostgREST), (跑通第一个 API); -- 匿名角色未携带 JWT 的请求用它执行 CREATE ROLE anon NOLOGIN; GRANT USAGE ON SCHEMA api TO anon; GRANT SELECT ON api.todos TO anon; GRANT USAGE ON SEQUENCE api.todos_id_seq TO anon; -- 认证器角色PostgREST 用它连接数据库再变身成其他角色 CREATE ROLE authenticator LOGIN NOINHERIT PASSWORD secret_password; GRANT anon TO authenticator;注意这里的角色设计已经体现了 PostgREST 的权限思想匿名用户默认只给了SELECT和序列使用权——想让匿名请求能 POST才需要再GRANT INSERT。表结构决定了 API 端点长什么样比如带外键的关联表可以被select参数直接嵌入原理可以看官方文档里的 ER 示例第 2 步写配置文件新建postgrest.conf跑通最小闭环只需要四项db-uri postgres://authenticator:secret_passwordlocalhost:5432/mydb db-schemas api db-anon-role anon jwt-secret reallyreallyreallyreallyverysafe # 至少 32 字符db-uri里的用户就是认证器角色不是普通的数据库账号db-schemas决定哪些 schema 会变成 API 端点db-anon-role缺省时匿名请求会被拒绝jwt-secret缺省时无法验证带 JWT 的请求。完整参数语义可参考 docs/references/configuration.rst也可以执行postgrest -e生成一份带注释的样例配置。第 3 步启动服务postgrest postgrest.conf # 看到类似 Starting PostgREST 的启动日志即成功Docker 方式则通过环境变量传入同样的配置docker run -p 3000:3000 \ -e PGRST_DB_URIpostgres://authenticator:secret_passworddb:5432/mydb \ -e PGRST_DB_SCHEMASapi \ -e PGRST_DB_ANON_ROLEanon \ -e PGRST_JWT_SECRETreallyreallyreallyreallyverysafe \ postgrest/postgrest第 4 步用 curl 验证 CRUD# 读拿到全部待办 curl http://localhost:3000/todos # 条件过滤 字段选择 排序 curl http://localhost:3000/todos?doneis.falseselectid,taskorderid.desc # 写创建一条匿名角色无 INSERT 权限会返回 401/403——这是预期的 curl -X POST http://localhost:3000/todos \ -H Content-Type: application/json \ -d {task: 写文档}如果你给anon补上GRANT INSERT ON api.todos TO anon再发一次 POST 就会返回 201 和新记录——改一行 GRANTAPI 能力就变了这就是 PostgREST 与自研 API 最大的不同。更新与删除同样走查询参数定位行curl -X PATCH http://localhost:3000/todos?ideq.2 \ -H Content-Type: application/json -d {done: true} curl -X DELETE http://localhost:3000/todos?ideq.3访问根路径http://localhost:3000/还能拿到自动生成的 OpenAPI 文档客户端代码可以直接基于它生成。PostgREST 权限模型三类角色如何把安全交给数据库这一节解释一个请求从进来到落地身份是怎么被确认和降权的理解它你就不会在权限配置上踩坑。请求鉴权链路三类角色各就各位角色职责关键约束认证器db-uri中的用户唯一与数据库建立连接的角色随后SET ROLE变身必须NOINHERIT且只能被 GRANT 到它允许扮演的角色匿名角色db-anon-role承接所有未携带 JWT 的请求建议只给只读权限甚至可以不设置直接封死匿名访问用户角色JWT 中的role声明每个真实用户的身份必须 NOLOGIN只能被认证器变出来权限按最小化授予PostgREST 把 JWT 的role声明与数据库角色名对应起来所以签发令牌时 payload 里写role: todo_user请求进来后数据库里执行的就是SET ROLE todo_user。用在线 JWT 工具对照 secret 签发、验签的过程如下HS256 对称签名两层防线表级授权 行级安全最小权限按角色精确GRANT例如匿名用户只能SELECT公开表管理角色才能触碰敏感表。API 的行为上限 角色的权限上限。RLS行级安全表级授权管能不能碰这张表RLS 管能看到哪些行。开启 RLS 后策略里可以直接读取 PostgREST 注入的request.jwt.claims把user_id与 JWT 声明比对实现每个用户只看到自己的数据。官方对这两层机制有专门讲解见 docs/explanations/db_authz.rst。配置项按目的归类速查完整参数文档很长这里按你想解决什么问题分成四组只列最常用的。所有参数都可用PGRST_前缀的同名环境变量覆盖如db-pool对应PGRST_DB_POOL。连接与连接池参数类型默认值说明示例db-uriStringpostgresql://PostgreSQL 连接串用户即认证器角色postgres://auth:passdb:5432/appdb-poolInt10连接池最大连接数不可热重载20db-pool-acquisition-timeoutInt10请求等待空闲连接的上限秒30db-pool-max-lifetimeInt1800池中连接最大存活时间秒3600db-pool-automatic-recoveryBooleantrue连接断开后是否自动重连false安全与认证参数类型默认值说明示例db-schemasStringpublic暴露为 API 端点的 schema 列表api, v1db-anon-roleString无匿名请求使用的角色不设置则拒绝匿名anonjwt-secretString无JWT 验签密钥必须 ≥32 字符文件名可从文件读取./secrets/jwt.txtjwt-secret-is-base64Booleanfalse密钥是否按 base64 解码truejwt-role-claim-keyString$.role从 JWT 哪个声明提取角色名$.https://app/rolejwt-audString无额外校验 JWT 的aud声明api-v1服务器与网络参数类型默认值说明示例server-portInt3000监听端口0表示自动分配8080server-hostString!4绑定地址127.0.0.1server-cors-allowed-originsString无CORS 白名单不设置 放行所有来源https://myapp.comserver-timing-enabledBooleanfalse返回 Server-Timing 头便于排障trueadmin-server-portInt无独立管理端口健康检查、metrics3001高级与 OpenAPI参数类型默认值说明示例db-max-rowsInt无限制单次查询最大返回行数防大结果集打爆内存1000db-aggregates-enabledBooleanfalse允许selectcount(*)等聚合truedb-plan-enabledBooleanfalse允许通过 Accept 头请求执行计划truedb-pre-requestString无每个请求执行前调用的钩子函数审计、限流api.hook_pre_requestopenapi-modeStringfollow-privilegesOpenAPI 文档按调用者权限裁剪 / 忽略权限 / 禁用disabledclient-error-verbosityStringverbose返回给客户端的错误细节程度minimallog-levelStringerror日志级别crit/error/warn/info/debuginfo两个容易忽略的点配置支持热重载发送SIGUSR2或在数据库里NOTIFY pgrst, reload config改完配置不用重启如果数据库前面挂了 PgBouncer 的 transaction pooling 模式要把db-prepared-statements和db-channel-enabled都设为false。上生产前的 PostgREST 部署自检清单发布前逐项过一遍能挡掉绝大多数线上事故。连接与容量db-pool与数据库max_connections匹配多实例部署时总池量不超限设置了db-max-rows避免select*一次拉回百万行数据库在高并发下连接打满时db-pool-acquisition-timeout有合理值客户端能看到 503 而不是无限挂起认证与密钥jwt-secret至少 32 字符且通过环境变量或文件注入不要写进配置文件再提交到版本库确认db-anon-role的权限是确实需要的最小集匿名能写数据的大多是配置失误多环境共享签发方时配置了jwt-aud防止 A 环境的 token 打到 B 环境涉及多租户或私有数据时关键表已开启 RLS并且策略读取的是 JWT claims 而不是可伪造的请求头网络与输出server-cors-allowed-origins已显式配置默认放行所有来源是常见漏配openapi-mode明确取值对外 API 建议disabled或follow-privileges避免信息暴露client-error-verbosity minimal防止数据库内部细节经错误信息泄露log-level info起步配合admin-server-port暴露健康检查行为验证故意用错误/过期/伪造签名的 JWT 请求一次确认返回 401 而不是 200访问未授权端点确认返回 404/403修改配置后执行热重载killall -SIGUSR2 postgrest确认新配置生效用db-pre-request钩子或数据库审计表抽查一条写操作确认身份链路认证器 → 目标角色符合预期下一步学什么跑通 CRUD 只是起点PostgREST 的天花板由你的数据库设计决定关联嵌入查询利用外键在 URL 里嵌套查询关联表select*,films(*)把多表 JOIN 变成一次请求详见 docs/references/api/resource_embedding.rstRPC 与钩子函数把复杂业务逻辑写成数据库函数暴露为 RPC 端点配合db-pre-request做审计和限流部署运维进阶多实例负载均衡、PgBouncer 外部连接池、只读副本与零停机配置更新可参考 docs/explanations/architecture.rst 了解请求在各组件间的流转。把权限设计好、把 schema 划分清楚PostgREST 就会持续替你把数据库翻译成一套稳定、自描述的 REST API。【免费下载链接】postgrestREST API for any Postgres database项目地址: https://gitcode.com/GitHub_Trending/po/postgrest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考