PostGraphile v5 部署到 Heroku 完整指南：AWS RDS 与 Heroku Postgres 实战配置

PostGraphile v5 部署到 Heroku 完整指南AWS RDS 与 Heroku Postgres 实战配置【免费下载链接】crystal Graphiles Crystal Monorepo; home to Grafast, PostGraphile, pg-introspection, pg-sql2 and much more!项目地址: https://gitcode.com/gh_mirrors/cry/crystal本文基于 PostGraphile v5Crystal Monorepo 中的postgraphile包官方部署文档系统讲解将 PostGraphile GraphQL API 部署到 Heroku 的全部可行路径从 AWS RDS 与 Heroku Postgres 两种数据库方案的选型对比到 CLI 极简部署与以库形式嵌入的自定义部署两种应用形态覆盖连接字符串、SSL、多角色凭据、环境变量、Procfile、Node 版本声明等全部关键配置并提供源码级的原理佐证帮助你一步到位完成生产级部署。部署前的核心决策用哪种 PostgreSQL将 PostGraphile 部署到 Heroku 时你需要在两种 PostgreSQL 数据库方案中做出选择Amazon RDS或Heroku Postgres。官方文档给出了明确倾向这个选择直接影响后续的账号体系与连接方式。为什么推荐 AWS RDSPostGraphile 的典型用法需要为管理员与访问者建立不同的 PostgreSQL 角色管理员角色如postgraphile负责在启动时执行 DDL 迁移访问者角色如postgraphile_visitor则由 PostGraphile 在每个请求中通过SET ROLE切换实现细粒度的行级安全与权限隔离。而Heroku Postgres 不允许执行CREATE ROLE命令这意味着你无法在 Heroku 托管的数据库上直接创建这些角色虽然可以绕开详见下文Heroku Postgres一节。因此官方建议优先使用Amazon RDS PostgreSQL搭配 Heroku 运行应用层在 RDS 控制台启用force_ssl设置强制数据库侧要求 SSL 连接为了让 PostGraphile 以 SSL 方式连接 RDS需要在连接字符串末尾追加?ssltrue例如heroku config:set DATABASE_URLpostgres://...rdshost.../db_name?ssltrue同时应遵循 Heroku 与 AWS 给出的其他安全建议如限制安全组访问、启用备份等避免使用 RDS 最低档的 PostgreSQL 实例因为其 I/O 积分上限过低一旦流量上来很快就会拖垮整个实例原文it can very quickly grind to a halt。在 Heroku Postgres 上工作的绕行方案如果坚持使用 Heroku Postgres官方也给出了可行但更麻烦且更花钱的路径。核心问题在于Heroku Postgres 不允许CREATE ROLE因此你需要改用 Heroku 自带的**凭据credentials**机制来扮演不同角色数据库档位要求数据库必须为Standard-0 档约 $50/月或更高否则无法创建额外的凭据。为每个需要的角色创建凭据登录 https://data.heroku.com为每个要使用的 PostgreSQL 角色创建凭据。例如postgraphile——应用登录数据库时使用的凭据postgraphile_visitor——PostGraphile 在每个请求中切换到的角色用于权限隔离。将凭据附加到应用把postgraphile凭据附加到你的 Heroku 应用使应用上同时存在两个凭据default和postgraphile。改用POSTGRAPHILE环境变量在应用代码中使用POSTGRAPHILE环境变量而非DATABASE_URL来连接这个凭据对应的数据库地址。不要忘记 SSL通过PGSSLMODErequire等环境变量启用 SSL 连接。关于 Heroku Postgres 凭据机制的完整说明可参考 Heroku 官方文档Heroku Postgres Credentials原文给出了该外部链接。从源码可以印证这种每请求切换角色的设计意图dataplan/pg的适配器在 grafast/dataplan-pg/src/adaptors/pg.ts 中通过withPgClient将数据库客户端注入 Grafast 上下文而 PostGraphile 的权限体系正是围绕登录角色 请求内切换角色构建的。理解这一点你就明白为什么创建角色能力是数据库选型的硬约束。极简部署使用 PostGraphile CLI如果你只需要一个开箱即用的 GraphQL API最快的方式是用postgraphile的 CLI 命令直接启动服务配合一个graphile.config.mjs配置文件完成 Heroku 适配。完整步骤如下# 1. 创建项目目录 mkdir project_folder_name # 2. 进入目录并初始化 git cd project_folder_name git init # 3. 安装 postgraphile yarn add postgraphile # 4. 提交初始代码 git add . git commit -m Initial commit # 5. 添加 Heroku 远程仓库 heroku git:remote -a heroku_app_name # 6. 配置数据库连接 URL此处以 RDS 为例 heroku config:set RDS_URLpostgres://user:passrdshost/dbname?ssltrue -a heroku_app_name第 7 步在项目根目录创建graphile.config.mjsimport { PostGraphileAmberPreset } from postgraphile/presets/amber; import { makePgService } from postgraphile/adaptors/pg; export default { extends: [PostGraphileAmberPreset], pgServices: [makePgService({ connectionString: process.env.RDS_URL })], grafserv: { host: 0.0.0.0, port: parseInt(process.env.PORT, 10), }, };这份配置是 CLI 部署的核心逐项说明其含义PostGraphileAmberPresetPostGraphile v5 的官方推荐预设聚合了 Graphile Build 与 Graphile Build PG 的默认插件集并对插件顺序做了 V4 兼容性整理。其定义位于 postgraphile/postgraphile/src/presets/amber.ts从源码可见它extends了orderedPlugins、graphileBuildPreset、graphileBuildPgPreset并额外引入SwallowErrorsPlugin。该预设通过postgraphile/presets/amber这个子路径导出见 postgraphile/postgraphile/package.json 中的exports字段。makePgService({ connectionString })来自postgraphile/adaptors/pg其底层实现是dataplan/pg适配器的 makePgService会基于connectionString创建 PostgreSQL 连接池PgPool并支持poolConfig、superuserConnectionString、schemas等选项。这里把连接字符串指向环境变量RDS_URL避免把密钥写进仓库。grafserv.host: 0.0.0.0必须绑定到所有网络接口Heroku 的路由层才能把外部请求转发给容器。从 grafast/grafserv/src/index.ts 的类型定义可见host即要监听的地址Host to listen on。grafserv.port: parseInt(process.env.PORT, 10)Heroku 会通过环境变量PORT动态分配端口通常为随机高位端口应用必须监听该端口才能被 Heroku 路由发现parseInt负责把字符串转换为数字因为 grafserv 的port选项是数字类型。第 8 步创建Procfile声明 web 进程的启动命令echo web: postgraphile Procfile第 9 步推送到 Heroku 触发构建与部署git push heroku masterCLI 在启动时会读取根目录的graphile.config.mjs或graphile.config.js。对应实现位于 postgraphile/postgraphile/src/cli.ts它通过loadConfig加载用户配置文件与命令行参数合并后调用resolvePreset解析预设随后经postgraphile(config)构建 schema、createServ(grafserv)创建 HTTP 服务并监听config.grafserv?.port。这也意味着你完全可以用命令行参数如--connection、--port、--host覆盖配置文件中的对应项。自定义部署将 PostGraphile 作为库使用当你的应用需要与 GraphQL API 共享进程例如同时提供 REST 接口、后台任务、邮件发送等能力时CLI 就不够用了此时应该把 PostGraphile 作为库嵌入自己的 Node.js 服务。这个方案适合已经有本地 git 仓库的项目。第一步编写 Procfile 与 package.json在仓库根目录创建Procfile告诉 Heroku 启动时运行什么web: yarn start同时确保package.json中包含构建与启动脚本并用engines声明 Node 版本让 Heroku 选择正确的运行时{ scripts: { build: tsc, start: node server.js }, engines: { node: 24 } }注原文档此处同时给出了两个engines片段24与12.x这属于文档历史遗留的示例堆叠实际项目中只需声明一个即可。就当前仓库而言postgraphile包自身的 package.json 声明的engines.node为22因此你的运行时声明不应低于此门槛。如果你使用 TypeScriptbuild脚本如tsc会在 Heroku 的 slug 构建阶段执行产物如server.js再由start脚本运行。提交这些文件。第二步创建应用并配置环境变量确保数据库服务已运行、数据库及相关角色已创建完毕后执行以下操作这些命令大多也可以用 Heroku 网页控制台完成1. 创建 Heroku 应用heroku create myappname2. 设置配置变量heroku config:set \ NODE_ENVproduction \ GRAPHILE_ENVproduction \ DATABASE_URLpostgres://username:passwordhost:port/dbname?ssltrue \ -a myappname三个变量的作用NODE_ENVproduction让 Node 运行时与依赖库进入生产模式禁用开发期调试输出等。GRAPHILE_ENVproductionGraphile 生态Grafast/grafserv的开发模式开关。从源码看grafast/grafserv/src/options.ts 中的makeMaskError会根据isDev决定是否启用开发期错误包装在非开发环境下错误会经过掩码处理以避免泄露内部实现细节——这正是生产部署必须显式设置该变量的原因。DATABASE_URL连接字符串必须带?ssltrue针对 RDS确保走 SSL 加密通道。3. 添加 git 远程并推送git remote add heroku githeroku.com:myappname.git git push heroku master推送前请确保已把 SSH 公钥上传到 Heroku。推送后你会看到构建日志滚动输出如果构建失败日志会告诉你失败原因。成功后应用将可通过https://myappname.herokuapp.com访问。第三步在应用代码中启动 PostGraphile以库方式使用时你的server.js或编译后的 TS 产物内部大致如下import { postgraphile } from postgraphile; import { grafserv } from grafserv/node; // 读取上面配置的预设可来自 graphile.config.mjs const pgl postgraphile(preset); const serv pgl.createServ(grafserv); serv.addTo(require(node:http).createServer()).then(() { // 监听 Heroku 分配的 PORT });这与 CLI 的内部路径完全一致postgraphile(preset)先解析预设、构建 schema再通过createServ(grafserv)创建服务实例并挂载到 HTTP server 上参见 postgraphile/postgraphile/src/index.ts。你可以在自己的 Express/Fastify/Hono 等框架之上组合使用。清理销毁 Heroku 应用当不再需要该应用时注意这是删除操作会同时移除应用及其配置变量请确认数据已备份或不再需要heroku apps:destroy -a myappname进阶提示更自动化的生产设置原文档建议若需要配置后台任务队列、发送邮件等更完整的自动化部署可参考 Graphile Starter 项目的Deploying to Heroku章节原文给出的外部链接。watch 模式在生产环境的取舍PostGraphile v5 支持grafserv.watchCLI 对应--watch监听数据库 schema 变化并热更新 GraphQL schema实现见 postgraphile/postgraphile/src/index.ts 的watchSchema分支。生产环境通常不建议开启schema 变更应通过受控的迁移流程发布。安全基线无论选择哪种数据库都应启用 SSL、遵循 Heroku/AWS 的安全建议、不要把连接凭据硬编码进仓库——它们只应存在于 Heroku config vars 或本地的环境变量中。【免费下载链接】crystal Graphiles Crystal Monorepo; home to Grafast, PostGraphile, pg-introspection, pg-sql2 and much more!项目地址: https://gitcode.com/gh_mirrors/cry/crystal创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考