Configuration配置
No matter whether you’re using PostGraphile CLI, library mode or schema only,
PostGraphile (and other elements of the stack including Graphile Build,
Grafast and Grafserv) are configured via a graphile-config
“preset.”
无论你使用的是 PostGraphile CLI、库模式,还是纯 schema 模式,PostGraphile 以及技术栈中的其他组件(包括 Graphile Build、Grafast 和 Grafserv)都通过 graphile-config 的“preset”进行配置。
A preset is a simple JS object that contains a combination of: other presets, plugins, and options for the various scopes. Your configuration, your preset, will almost certainly need to extend an existing preset or presets; which preset(s) to extend depends on what you’re looking for from PostGraphile.
preset 本质上是一个简单的 JS 对象,用来组合其他 preset、插件以及各个作用域(scope)的配置选项。你的配置(即你的 preset)几乎总是需要继承一个或多个现有 preset;具体继承哪些,取决于你希望启用 PostGraphile 的哪些功能。
The PostGraphile base presets are named after crystals; the first base preset
available is postgraphile/presets/amber, so you’ll almost definitely want
that.
PostGraphile 的基础 preset 均以晶体命名;目前已有的第一个基础 preset 是 postgraphile/presets/amber,绝大多数情况下你都需要引入它。
Please don’t name your own presets after crystals, or we may end up having confusion!
请不要用晶体名称来命名你自己的 preset,以免造成混淆!
Creating your configuration file创建配置文件
Though you can build a preset anywhere in your source code and pass it to the
relevant APIs, we recommend that you put your preset into a
graphile.config.mjs (or .ts or .mts or .js etc) file, so that it can
easily be picked up by the PostGraphile CLI and any other utilities (e.g. the
graphile command). You may write your preset in either JS or TS, and you may
expose it as either CommonJS (module.exports = ...;) or ESM (export default ...;). In our examples, we’ll typically use .mjs since it’s modern but
without the overhead of requiring TypeScript.
虽然你可以在源码的任意位置构建 preset 并将其传入相关 API,但我们建议把它放在 graphile.config.mjs(或 .ts、.mts、.js 等)文件中,方便 PostGraphile CLI 及其他工具(例如 graphile 命令)自动识别。你可以用 JS 或 TS 编写 preset,也可以通过 CommonJS(module.exports = ...;)或 ESM(export default ...;)形式导出。本文档中的示例通常采用 .mjs 格式,既能使用现代模块语法,又免去了引入 TypeScript 的额外配置成本。
Here’s an example preset which only extends the “Amber” preset:
下面是一个仅继承“Amber” preset 的示例:
// @ts-check
import { PostGraphileAmberPreset } from "postgraphile/presets/amber";
/** @type {GraphileConfig.Preset} */
const preset = {
extends: [PostGraphileAmberPreset],
};
export default preset;
Or in TypeScript:
或者使用 TypeScript:
import { PostGraphileAmberPreset } from "postgraphile/presets/amber";
const preset: GraphileConfig.Preset = {
extends: [PostGraphileAmberPreset],
};
export default preset;
Similarly, you can create your config as a .js, .cjs, .ts or .cts file;
the PostGraphile CLI will pick up all of these automatically assuming that you
have TypeScript installed locally and are running Node 24 or higher. (For Node
22.6+ you'll need to be running with the node --experimental-strip-types flag,
or have tsx, ts-node, or similar installed locally.)
同样,你也可以将配置文件创建为 .js、.cjs、.ts 或 .cts 文件;只要本地安装了 TypeScript 且运行在 Node 24 及以上版本,PostGraphile CLI 就能自动加载上述所有格式。(如果是 Node 22.6+,则需要加上 node --experimental-strip-types 参数运行,或在本地安装 tsx、ts-node 等工具。)
General structure基本结构
A preset is a plain JavaScript object, and every key in the preset is optional.
{} is a valid (but not very useful!) preset. The key default is forbidden
at the top level of a preset, this allows us to detect common issues with
ESM/CommonJS interoperability.
preset 是一个普通的 JavaScript 对象,其中的每个键都是可选的。{} 本身就是一个合法的 preset(虽然没什么实际用途!)。preset 顶层禁止出现 default 键,这有助于我们检测常见的 ESM 与 CommonJS 互操作问题。
The value for the extends key, if specified, must be an array of other presets
your preset wishes to inherit from.
如果指定了 extends 键,其值必须是一个数组,包含当前 preset 需要继承的其他 preset。
The value for the plugins key, if specified, must be an array of
graphile-config plugins
that your preset wishes to make use of. Plugins must always have unique names,
and will be automatically de-duplicated by the system if the same plugin is
referenced in multiple presets.
如果指定了 plugins 键,其值必须是一个由 graphile-config 插件组成的数组,用于指定当前 preset 要使用的插件。插件名称必须保持唯一;如果多个 preset 中引用了同一个插件,系统会自动去重。
The preset also accepts keys for each supported scope. graphile-config has no
native scopes, but different Graphile projects can register their own scopes.
For example: graphile-build registers the inflection, gather and schema
scopes; graphile-build-pg registers the pgServices scope; Grafast
registers the grafast scope; Grafserv registers the grafserv scope; and
ruru registers the ruru scope.
preset 还支持以各个受支持的作用域(scope)作为配置键。graphile-config 本身没有内置任何原生作用域,但不同的 Graphile 项目可以注册各自的作用域。例如:graphile-build 注册了 inflection、gather 和 schema 作用域;graphile-build-pg 注册了 pgServices 作用域;Grafast 注册了 grafast 作用域;Grafserv 注册了 grafserv 作用域;ruru 则注册了 ruru 作用域。
We highly recommend using TypeScript for dealing with your preset so that you
get auto-completion for the options available in each scope; you can also use
the graphile config options command detailed below.
我们强烈建议使用 TypeScript 来编写和维护 preset,以便获得各个作用域可用配置项的自动补全;此外,你也可以使用下文介绍的 graphile config options 命令。
The schema build process in PostGraphile is:
PostGraphile 中的 schema 构建流程如下:
-
Synchronously build the inflectors via the
inflectionphase - inflectors are used throughout the phases在
inflection阶段同步构建 inflector(命名推导器)——整个流程的各个阶段都会用到 inflector -
Asynchronously build the registry by performing database introspection in the
gatherphase在
gather阶段通过数据库 introspection 异步构建 registry -
Synchronously determine the behaviors of each of the entities in the registry during the
behaviorphase在
behavior阶段同步确定 registry 中各个实体的 behavior -
Synchronously build the GraphQL schema during the
schemaphase在
schema阶段同步构建 GraphQL schema
Simple example简单示例
import { PostGraphileAmberPreset } from "postgraphile/presets/amber";
import { makePgService } from "postgraphile/adaptors/pg";
const preset: GraphileConfig.Preset = {
extends: [PostGraphileAmberPreset],
grafserv: { port: 5678 },
pgServices: [makePgService({ connectionString: "postgres:///my_db" })],
};
Larger example综合示例
// The standard base preset to use, includes the main PostGraphile features
import { PostGraphileAmberPreset } from "postgraphile/presets/amber";
// More presets you might want to mix in
import { makeV4Preset } from "postgraphile/presets/v4";
import { PostGraphileRelayPreset } from "postgraphile/presets/relay";
// Use the 'pg' module to connect to the database
import { makePgService } from "postgraphile/adaptors/pg";
// A plugin for the system to use for persisted operations support
import PersistedPlugin from "@grafserv/persisted";
const preset: GraphileConfig.Preset = {
extends: [
PostGraphileAmberPreset,
/* Add more presets here, e.g.: */
makeV4Preset({
simpleCollections: "both",
jwtPgTypeIdentifier: '"b"."jwt_token"',
dynamicJson: true,
graphiql: true,
graphiqlRoute: "/",
}),
// Uncomment this to opt into a smaller Relay-focussed schema
//PostGraphileRelayPreset,
],
plugins: [
/* Add plugins here, e.g.: */
PersistedPlugin,
],
inflection: {
/* options for the inflection system */
},
gather: {
/* options for the gather phase, e.g.: */
pgStrictFunctions: true,
installWatchFixtures: true,
},
schema: {
/* options for the schema build phase, e.g.: */
retryOnInitFail: true,
exportSchemaSDLPath: `${process.cwd()}/latestSchema.graphql`,
exportSchemaIntrospectionResultPath: `${process.cwd()}/latestSchema.json`,
sortExport: true,
},
grafast: {
/* options for Grafast, including setting GraphQL context, e.g.: */
context: {
meaningOfLife: 42,
},
// explain: true, // DO NOT ENABLE IN PRODUCTION!
},
grafserv: {
/* options for Grafserv, e.g.: */
port: 5678,
graphqlPath: "/graphql",
websockets: true,
graphqlOverGET: true,
persistedOperationsDirectory: `${process.cwd()}/.persisted_operations`,
allowUnpersistedOperation: true,
},
ruru: {
/* options for customizing Ruru, e.g.: */
htmlParts: {
metaTags: (base) => base + "<!-- HELLO WORLD! -->",
},
},
pgServices: [
/* list of PG database configurations, e.g.: */
makePgService({
// Database connection string, read from an environmental variable:
connectionString: process.env.DATABASE_URL,
// List of database schemas to expose:
schemas: ["app_public"],
// Enable LISTEN/NOTIFY:
pubsub: true,
}),
],
};
export default preset;