Skip to main content

This quick start guide will walk you through spinning up your firstPostGraphile server, including installing the prerequisites such as Node and PostgreSQL.

本快速入门指南将带你一步步启动你的第一个 PostGraphile 服务器,包括安装 Node 和 PostgreSQL 等前置依赖。

Table of Contents目录

Install Node安装 Node​

You need to be running Node.js 22 or higher to run PostGraphile, and we recommend Node.js 24 or higher. You can check your current version of Node by running node --version. If you're running a recent version you can skip this section.

运行 PostGraphile 需要 Node.js 22 或更高版本,推荐使用 Node.js 24 或更高版本。你可以运行 node --version 查看当前的 Node 版本。如果你已经安装了较新的版本,可以跳过本节。

There's many ways of installing node; if you're on macOS you might prefer installing with homebrew via brew install node; if you're on a unix-based system you might like to use the nvm tool. Failing these, if you're using OS X or Windows, use one of the installers from the Node.js download page. Make sure you select the version labelled LTS. Linux users can scroll down the page and find the version that works with their system.

安装 Node 的方式有很多:在 macOS 上,你可以用 Homebrew 执行 brew install node;在类 Unix 系统上,也可以使用 nvm 工具。如果上述方式都不适用,OS X 或 Windows 用户可以前往 Node.js 下载页面获取安装程序,请务必选择标注为 LTS 的版本;Linux 用户则可以向下滚动页面,找到适合自己系统的版本。

Once installed run node -v in a terminal to check your version. It must be 22.0.0 or higher; 24.0.0 or higher is recommended.

安装完成后,在终端中运行 node -v 检查版本号。版本必须为 22.0.0 或更高(推荐 24.0.0 或更高)。

Install PostgreSQL安装 PostgreSQL​

We need a PostgreSQL database to connect to. You can skip this section if you already have PostgreSQL version 14.0 or higher installed. If you do not use a local PostgreSQL server then you'll need to modify the commands that follow to account for this.

我们需要一个可供连接的 PostgreSQL 数据库。如果你已经安装了 14.0 或更高版本的 PostgreSQL,可以跳过本节。如果你使用的不是本地 PostgreSQL 服务器,则需要相应调整后续命令中的连接参数。

tip提示

PostgreSQL does not need to be installed on the same machine, but you'll have a better development experience if it is. Try and minimise database connection latency — do not use a database on the other side of the planet from you!

PostgreSQL 并不一定要安装在同一台机器上,但部署在本地通常会带来更好的开发体验。请尽量降低数据库连接延迟——千万不要去连一台远在地球另一端的数据库!

If you are running on macOS, it is recommended that you install and use PostgreSQL.app. If you are on another platform, go to the PostgreSQL download page to pick up a copy of PostgreSQL. The latest LTS version is probably a good choice, but please refer to the requirements documentation.

如果你使用的是 macOS,推荐安装并使用 PostgreSQL.app。如果在其他平台上,请前往 PostgreSQL 下载页面获取安装包。选择最新的 LTS 版本通常是个不错的选择,具体要求请参阅系统要求文档。

After that, make sure your copy of PostgreSQL is running locally by running psql postgres:/// in a terminal (the three slashes is deliberate — we're deliberately not specifying a host so it uses the defaults (either a unix socket or hostname: localhost, port: 5432).

之后,在终端中运行 psql postgres:/// 确认本地 PostgreSQL 正在运行(注意这里刻意使用了三个斜杠——故意不指定主机名,以便使用默认设置,即 Unix socket 或主机名 localhost、端口 5432)。

If you get something like this returned then PostgreSQL is successfully installed:

如果终端返回类似下面的输出,说明 PostgreSQL 已成功安装:

$ psql "postgres:///"

psql: FATAL: database "username" does not exist

however, if you receive a "Connection refused" error then that indicates your PostgreSQL server is not running, or not reachable:

不过,如果收到“Connection refused”错误,则说明 PostgreSQL 服务器尚未启动或无法连接:

$ psql "postgres:///"

psql: could not connect to server: Connection refused

If you want to connect to a different database within PostgreSQL, just add the database name to the end of the connection string:

如果想连接到 PostgreSQL 中的其他数据库,只需将数据库名称追加到连接字符串末尾即可:

psql postgres:///testdb # Connects to the `testdb` database on your local machine
psql "postgres://user:password@somehost:2345/somedb" # Connects to the `somedb` database at `postgres://somehost:2345` using login with `user` and `password`

Read the documentation on PostgreSQL connection strings to learn more about alternative formats (including using a password).

要了解更多其他连接格式(包括如何指定密码),请参阅 PostgreSQL 连接字符串文档。

Create a Database创建数据库​

Next, create a database. You can do this by using the terminal:

接下来创建一个数据库。你可以在终端中执行以下命令:

createdb mydb

This will create a PostgreSQL database called "mydb". You can read more about this on the PostgreSQL Documentation site. Now you can run psql with your database URL and get a SQL prompt:

这会创建一个名为“mydb”的 PostgreSQL 数据库。你可以在 PostgreSQL 官方文档中了解更多细节。现在,你可以带上数据库 URL 运行 psql,进入 SQL 交互提示符:

psql "postgres:///mydb"
psql (14.*)
Type "help" for help.

=#

Run the following query to make sure things are working smoothly:

执行以下查询,确认一切运行正常:

select 1 + 1 as two;
two
-----
2
(1 row)

Install PostGraphile安装 PostGraphile​

Use your package manager of choice to install the postgraphile module: npm:

使用你偏好的包管理器(例如 npm)安装 postgraphile 模块:

npm install --save postgraphile
tip提示

We do not recommend installing PostGraphile globally (e.g. with the -g flag to npm) — local installs are preferred. Though it may seem simpler to use global installs at first, it will become more complicated and give you hard to debug errors, so even if you're new to Node we suggest you get used to local installs.

我们不建议全局安装 PostGraphile(例如给 npm 加上 -g 参数)——更推荐在项目本地安装。全局安装乍看之下似乎更省事,但后续往往会带来更复杂、更难排查的报错,因此即便你是 Node 新手,我们也建议尽早习惯本地安装。

Running PostGraphile运行 PostGraphile​

To run PostGraphile, since we've installed postgraphile locally, we need to use the npx command (or yarn if you prefer) so that the system can find the local binary. We then pass a standard preset, and the same URL that you used for psql with the database name added:

由于我们将 postgraphile 安装在了项目本地,运行它时需要使用 npx(如果你习惯用 Yarn,也可以用 yarn),以便系统找到本地可执行文件。接着传入一个标准 preset,以及之前在 psql 中使用的那个带数据库名称的 URL:

# Connect to the `mydb` database within the local PostgreSQL server
npx postgraphile -P postgraphile/presets/amber -c "postgres:///mydb"

# Connect to a database that requires SSL/TLS
npx postgraphile -P postgraphile/presets/amber -c "postgres://securehost:5432/db?ssl=true"

# Connect to the `somedb` database within the PostgreSQL at somehost port 2345
npx postgraphile -P postgraphile/presets/amber -c "postgres://somehost:2345/somedb"

You can also run PostGraphile with the watch flag:

你也可以带上 watch 标志来运行 PostGraphile:

npx postgraphile -P postgraphile/presets/amber -c "postgres:///mydb" --watch

With the --watch flag, PostGraphile will automatically update your GraphQL API whenever the PostgreSQL schemas you are introspecting change.

启用 --watch 标志后,每当正在进行 introspection 的 PostgreSQL schema 发生变化时,PostGraphile 都会自动更新你的 GraphQL API。

Configuring PostGraphile配置 PostGraphile​

Having to enter all these flags each time can become cumbersome, so we'll create a graphile.config.mjs file to store our configuration.

每次运行都要输入这么多命令行标志会很繁琐,因此我们可以创建一个 graphile.config.mjs 文件来存放配置。

A minimal config so you just don't need the -P postgraphile/presets/amber would be be:

如果只想省去 -P postgraphile/presets/amber 参数,最简配置如下:

graphile.config.mjs
import { PostGraphileAmberPreset } from "postgraphile/presets/amber";
export default { extends: [PostGraphileAmberPreset] };

An configuration equivalent to the CLI with the watch flag above would be:

与前面带 watch 标志的 CLI 命令等价的配置如下:

graphile.config.mjs
import { PostGraphileAmberPreset } from "postgraphile/presets/amber";
import { makePgService } from "postgraphile/adaptors/pg";

/** @type {GraphileConfig.Preset} */
const preset = {
extends: [PostGraphileAmberPreset],
pgServices: [makePgService({ connectionString: "postgres:///mydb" })],
grafserv: { watch: true },
};

export default preset;

(Read more about graphile.config.mjs, including how to write it in TypeScript, in the Configuration documentation.)

(关于 graphile.config.mjs 的更多说明,包括如何用 TypeScript 编写配置文件,请参阅配置文档。)

With this configuration in place, we no longer need to pass the flags, so we can just run PostGraphile as:

有了这份配置之后,我们就不再需要手动传递那些标志参数了,直接这样运行 PostGraphile 即可:

npx postgraphile

Writing GraphQL Queries编写 GraphQL 查询​

Running PostGraphile will give you a URL:

启动 PostGraphile 后,终端会输出一个 URL:

Server listening on port 5678 at http://127.0.0.1:5678/graphql

You can visit this URL in your web browser to see the Ruru (a Grafast flavoured GraphiQL IDE) interface, or you can issue GraphQL requests to this URL using a GraphQL client of your choosing.

你可以在浏览器中访问该 URL,打开 Ruru(一款 Grafast 风格的 GraphiQL IDE)界面;也可以通过你偏好的任意 GraphQL 客户端向此 URL 发送 GraphQL 请求。

Well done — you've got PostGraphile up and running!

大功告成——你已经成功把 PostGraphile 跑起来了!