Skip to main content

Deploying to Heroku

It's possible to use PostGraphile on Heroku with either AWS RDS or Heroku Postgres.

在 Heroku 上运行 PostGraphile 时,既可以搭配 AWS RDS,也可以使用 Heroku Postgres。

AWS RDS使用 AWS RDS​

We recommend using an Amazon RDS PostgreSQL database with Heroku since Heroku Postgres does not allow the issue of CREATE ROLE commands. (This can be worked around, see below.)

我们更推荐在 Heroku 中搭配 Amazon RDS PostgreSQL 使用,因为 Heroku Postgres 不允许执行 CREATE ROLE 语句(不过这一点也有变通方案,详见下文)。

You should enable the force_ssl setting in RDS, and to ensure PostGraphile connects to RDS using SSL you need to add ?ssl=true to the connection string, e.g. heroku config:set DATABASE_URL="postgres://...rdshost.../db_name?ssl=true"

建议在 RDS 中开启 force_ssl 设置,同时在连接字符串末尾加上 ?ssl=true,以确保 PostGraphile 通过 SSL 连接 RDS,例如:heroku config:set DATABASE_URL="postgres://...rdshost.../db_name?ssl=true"

You should also take any further recommended actions by Heroku and AWS to ensure the security of your database.

此外,也请遵循 Heroku 和 AWS 官方的各项安全建议来保障数据库安全。

We recommend against the lowest tier of PostgreSQL on Amazon RDS because it's I/O credit limits are too low and it can very quickly grind to a halt.

不建议使用 Amazon RDS PostgreSQL 的最低规格实例,因为其 I/O 积分额度过低,很容易耗尽并导致服务停滞。

Heroku Postgres使用 Heroku Postgres​

It is also possible to use PostGraphile with Heroku Postgres too with a bit more setup (and money!).

如果你愿意多做一些配置(并投入更多预算),也可以直接使用 Heroku Postgres:

  1. Create a database if not already. The database must be of the Standard-0 tier ($50/month) or higher, otherwise you will not be able to create additional credentials.

    如果尚未创建数据库,请先新建一个。实例规格必须达到 Standard-0(50 美元/月)或更高,否则无法创建额外凭证。

  2. Create credentials on https://data.heroku.com for each Postgres role that you wish to use. For example, create a credential for postgraphile (which your app will use to log in with) and postgraphile_visitor (which PostGraphile should switch into for each request).

    前往 https://data.heroku.com 为需要用到的每个 Postgres 角色分别创建凭证。例如,为 postgraphile(应用登录数据库所使用的角色)和 postgraphile_visitor(PostGraphile 处理每个请求时切换到的角色)各创建一个凭证。

  3. Attach the postgraphile credential to your app, so that there should now be two credentials attached to your app (default and postgraphile).

    将 postgraphile 凭证绑定到你的应用上,此时应用下应该关联了两个凭证(default 和 postgraphile)。

  4. Use the POSTGRAPHILE environment variable instead of DATABASE_URL in your app's code to connect to Postgres with this credential.

    在应用代码中使用 POSTGRAPHILE 环境变量替代 DATABASE_URL,以便通过该凭证连接 Postgres。

  5. Don't forget to use SSL too (e.g. with the env var PGSSLMODE=require)!

    别忘了同时启用 SSL(例如设置环境变量 PGSSLMODE=require)!

Minimal setup, using PostGraphile CLI极简配置(使用 PostGraphile CLI)​

  1. Create a project directory mkdir project_folder_name

    创建项目目录:mkdir project_folder_name

  2. Go into that directory and initialise git: cd project_folder_name && git init

    进入目录并初始化 Git 仓库:cd project_folder_name && git init

  3. Add postgraphile: yarn add postgraphile

    安装 PostGraphile:yarn add postgraphile

  4. Commit everything: git add . && git commit -m "Initial commit"

    提交所有文件:git add . && git commit -m "Initial commit"

  5. Add the heroku remote heroku git:remote -a heroku_app_name

    关联 Heroku 远程仓库:heroku git:remote -a heroku_app_name

  6. Configure Heroku to use the right url heroku config:set RDS_URL="postgres://user:pass@rdshost/dbname?ssl=true" -a heroku_app_name

    在 Heroku 中配置数据库连接 URL:heroku config:set RDS_URL="postgres://user:pass@rdshost/dbname?ssl=true" -a heroku_app_name

  7. Create graphile.config.mjs:

    创建 graphile.config.mjs:

    import { 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),
    },
    };
  8. Create Procfile: echo 'web: postgraphile' >> Procfile

    创建 Procfile:echo 'web: postgraphile' >> Procfile

  9. Deploy: git push heroku master

    执行部署:git push heroku master

More detailed setup, using PostGraphile as a library进阶配置(将 PostGraphile 作为库使用)​

This walkthrough assumes you have a local git repository containing your project.

本流程假设你的项目已经初始化了本地 Git 仓库。

First, you need to create a Procfile file in the root of your repo, telling Heroku what to run:

首先,在仓库根目录创建 Procfile 文件,告知 Heroku 如何启动应用:

web: yarn start

You may also want to ensure that your package.json contains a build script that builds your app (e.g. calling tsc if you're using TypeScript), and that you have engines defined to tell Heroku which version of Node to use:

同时建议确保 package.json 中包含构建脚本 build(例如使用 TypeScript 时调用 tsc),并通过 engines 字段指定 Heroku 使用的 Node 版本:

"scripts": {
"build": "tsc",
"start": "node server.js"
},
"engines": {
"node": ">=24"
},
"engines": {
"node": "12.x"
}

Commit all this.

提交以上更改。

Once your database server is running and the database and relevant roles have been created, you need to do the following (note: many of these commands can instead be accomplished with the Heroku web interface):

在数据库服务启动且数据库及相关角色已创建好之后,继续执行以下步骤(注:其中许多操作也可直接在 Heroku 网页端完成):

  • Create the Heroku app e.g. heroku create myappname

    创建 Heroku 应用,例如:heroku create myappname

  • heroku config:set \
    NODE_ENV="production" \
    GRAPHILE_ENV="production" \
    DATABASE_URL="postgres://username:password@host:port/dbname?ssl=true" \
    -a myappname
  • Add the Heroku app as a git remote to your local repository, e.g. git remote add heroku git@heroku.com:myappname.git (make sure you've uploaded your SSH key to Heroku)

    将 Heroku 应用添加为本地仓库的 Git 远端,例如 git remote add heroku git@heroku.com:myappname.git(请确保你已将 SSH 公钥上传至 Heroku);

  • Push the master branch from your repo to Heroku to perform your initial build: git push heroku master

    将仓库的 master 分支推送到 Heroku 以触发首次构建:git push heroku master

You should see the build scrolling past; if it fails then you should be able to see why and address it. If it succeeds then your application should be available at https://<myappname>.herokuapp.com

此时终端会滚动输出构建日志;如果构建失败,可根据日志排查原因并修复;如果成功,应用即可通过 https://<myappname>.herokuapp.com 访问。

For a more in-depth and automated setup, including instructions on configuring a job queue and sending emails, see the Deploying to Heroku instructions in Graphile Starter.

如需更完整、自动化的部署方案(包含任务队列与邮件发送等配置),请参阅 Graphile Starter 中的 Heroku 部署指南。

Cleanup清理资源​

To delete the Heroku app:

如需删除该 Heroku 应用,可执行:

heroku apps:destroy -a myappname