Requirements
PostGraphile is packaged as a Node.js module, you can install it with any Node
package manager such as npm or yarn (depending on your preference) — users
tend to have fewer issues with yarn, so we recommend it (but if you use yarn
"berry", we recommend using nodeLinker: node-modules in your .yarnrc.yml).
PostGraphile 以 Node.js 模块的形式发布,你可以按个人偏好使用 npm 或 yarn 等任意 Node 包管理器进行安装——根据用户反馈,使用 yarn 时遇到的问题往往更少,因此我们更推荐使用 yarn(如果你使用的是 Yarn “Berry” 版本,建议在 .yarnrc.yml 中配置 nodeLinker: node-modules)。
We recommend using the latest LTS version of Node.js and PostgreSQL, but we have
limited support for older versions, so long as they are still LTS. Using newer
released versions should generally work fine (we don't recommend using with
alpha/beta versions though), but if there's any issues let us know in an issue.
PostGraphile supports Node.js 22+ and recommends Node.js 24+ for the best
experience (including built-in type stripping for .ts files).
我们建议始终使用最新 LTS 版本的 Node.js 和 PostgreSQL;只要仍在 LTS 维护周期内的旧版本,我们也会提供有限支持。使用最新正式发布版通常都能正常工作(不过不建议用于 alpha/beta 测试版),如遇任何问题,欢迎提交 issue 反馈。PostGraphile 支持 Node.js 22+,并推荐使用 Node.js 24+ 以获得最佳体验(包括原生支持直接运行 .ts 文件时的类型剥离)。
Your PostgreSQL database你的 PostgreSQL 数据库
These aren't exactly "requirements", but they will impact your PostGraphile experience.
以下几点并非严格意义上的“硬性要求”,但会直接影响你使用 PostGraphile 的体验。
-
Use primary keys: if you don't have primary keys on your tables then they won't get the
nodeIdglobally unique identifier interface. Further if you don't have unique constraints then you won't be able to use the automatic update/delete mutations (since they need a way to identify the row to update/delete).使用主键:如果数据表没有定义主键,它就无法生成
nodeId全局唯一标识接口。此外,如果表上没有任何唯一约束,也将无法使用自动生成的更新/删除 mutation(因为这些操作需要唯一定位待更新或删除的数据行)。 -
Use foreign keys: we infer relations between tables using foreign key constraints; if you don't use these constraints then we won't know there's a relationship between the tables. There are plugins to get around this (using smart comments) but it's highly recommended that you use PostgreSQL's built in relations support.
使用外键:PostGraphile 会依据外键约束自动推导表与表之间的 relation;若未定义外键约束,系统就无法得知表间存在关联。虽然可以通过插件(配合 smart comment)绕过这一限制,但强烈建议优先使用 PostgreSQL 原生的关联约束机制。
-
Don't use column-based SELECT grants: column-based grants work well for
INSERTandUPDATE(especially when combined withPgRBACPlugin!), but they don't make sense forDELETEand they cause issues when used withSELECT. You cannotSELECT *which makes your life harder, and rules out some of our possible optimization strategies. Computed columns (where we pass the entire record to the function) typically have issues with column-basedSELECTgrants. It's recommended that you instead split your tables on permission boundaries and use one-to-one relations to join them together again — this also makes writing your RBAC/RLS policies simpler. If you want to omit a column entirely then you can give it the@behavior -*smart tag.不要使用列级 SELECT 授权:列级授权非常适用于
INSERT和UPDATE(尤其是配合PgRBACPlugin使用时),但对于DELETE毫无意义,且在SELECT上会引发诸多问题——你将无法执行SELECT *,不仅会增加日常使用复杂度,还会导致 PostGraphile 的部分优化策略无法启用;此外,计算列(需要将整行记录传入函数)在启用列级SELECT授权时也通常会出错。更推荐的做法是按权限边界拆分数据表,再通过一对一 relation 将其关联起来——这同时也能让 RBAC/RLS 策略的编写更加简洁。如果只是想在 GraphQL 中彻底隐藏某一列,可以为其添加@behavior -*smart tag。 -
Function restrictions: we have pretty good support for PostgreSQL functions, but there's some common function restrictions you should check out.
函数限制:我们对 PostgreSQL 函数提供了相当完善的支持,但仍存在一些常见的函数限制,建议提前查阅了解。
-
Use unique constraints rather than unique indexes when appropriate: we use unique constraints to create mutations such as
updateUserByUsername; note that "PostgreSQL automatically creates a unique index when a unique constraint or primary key is defined for a table." -- PG docs**在合适场景下使用唯一约束(unique constraints)**而非唯一索引(unique indexes):PostGraphile 会基于唯一约束生成诸如
updateUserByUsername之类的 mutation;需要注意,正如 PostgreSQL 文档所述:“当为表定义唯一约束或主键时,PostgreSQL 会自动创建一个唯一索引。” -
Use the defaults for formatting output; we only run tests for the defaults so if you change them you may face issues. (You may change
intervalstylesince we have specific handling code for that.)保持默认输出格式设置:我们的测试仅覆盖默认输出格式,修改这些设置可能会导致异常。(
intervalstyle除外,PostGraphile 对其做了专门的兼容处理,可以按需调整。) -
Use UTF8 encoding: GraphQL operates over the UTF8 character set, using different encodings may impact your ability to store/retrieve certain values.
使用 UTF8 编码:GraphQL 基于 UTF8 字符集运行,使用其他字符编码可能会影响特定字符值的存储或读取。
On top of this, standard PostgreSQL best practices apply: use indexes carefully for performance, use constraints and triggers to ensure your data is valid and consistent, etc.
除此之外,常规的 PostgreSQL 最佳实践同样适用:合理创建索引以保障查询性能,借助约束与触发器确保数据的有效性与一致性等。
Unique indexes唯一索引
PostGraphile treats unique constraints as data guarantees, but unique indexes as optimisations that you might remove later; this is why it only creates accessors and mutations from unique constraints by default.
PostGraphile 将唯一约束视为数据完整性保证,而把唯一索引看作日后可能会调整或移除的性能优化手段;因此,默认情况下它仅根据唯一约束生成对应的查询访问器(accessor)和 mutation。
If your tooling does not understand this subtlety and can only create unique indexes, you might want to opt in to treating unique indexes as if they were constraints by using a plugin. We've included an example plugin to achieve this below.
如果你使用的数据库管理工具没有区分这一细微差别、只能创建唯一索引,可以通过插件选择将唯一索引视同唯一约束处理。下面提供了一个实现该功能的示例插件。
Click to view plugin to treat unique indexes as constraints.点击查看将唯一索引视作唯一约束的插件代码。
Only use this if you are confident that all of your unique indexes are true constraints.
仅当你确信数据库中的所有唯一索引都代表真实的数据唯一性约束时,再启用此插件。
// WARNING: this plugin was reworked from a GitHub issue and is currently untested
// Ref: https://github.com/graphile/crystal/issues/2054
export const PgUniqueIndexesPlugin: GraphileConfig.Plugin = {
name: "PgUniqueIndexesPlugin",
version: "0.1.0",
description: "Treats unique indexes as if they were unique constraints.",
gather: {
hooks: {
async pgTables_PgResourceOptions(_, event) {
const { pgClass, resourceOptions } = event;
if (pgClass.relkind !== "r") return;
if (resourceOptions.parameters) return;
if (!resourceOptions.uniques) return;
const mutableUniques = [...resourceOptions.uniques];
resourceOptions.uniques = mutableUniques;
const indexes = pgClass.getIndexes().filter((idx) => idx.indisunique);
const existingUniqueAttributeSets = new Set(
mutableUniques.map((u) => JSON.stringify(u.attributes)),
);
for (const idx of indexes) {
const attributes = idx.getKeys();
if (!attributes.every((a) => a != null)) continue;
const attributeNames = attributes.map((a) => a.attname);
const hash = JSON.stringify(attributeNames);
if (existingUniqueAttributeSets.has(hash)) continue;
existingUniqueAttributeSets.add(hash);
const { description, tags = Object.create(null) } =
idx.getIndexClass()?.getTagsAndDescription() ?? {};
mutableUniques.push({
isPrimary: idx.indisprimary ?? false,
attributes: attributeNames,
description,
extensions: { tags },
});
}
},
},
},
};
Node.js: use the active LTSNode.js:使用处于活跃维护期的 LTS 版本
PostGraphile supports Node.js 22+ but recommends Node.js 24+ where possible. We only support LTS versions of Node.js. Once a Node.js version reaches end-of-life we no longer support it, and any future patch release may be incompatible with it. We do not see this as a violation of semver — once a Node.js version reaches EOL no reasonable user should use it, and as such a change to drop support for it is not a breaking change for reasonable users.
PostGraphile 支持 Node.js 22+,并在条件允许时推荐使用 Node.js 24+。我们仅支持 Node.js 的 LTS 版本。一旦某个 Node.js 版本结束生命周期(EOL),我们将不再提供支持,后续任意补丁版本都可能不再兼容该版本。我们不认为这违背了语义化版本规范(semver)——当某个 Node.js 版本进入 EOL 后,正常情况下已不应继续使用它,因此移除对其的支持对合理使用环境而言并不构成破坏性变更。
TypeScript v5.0.0+ (optional)TypeScript v5.0.0+(可选)
We recommend that you use TypeScript for the best experience — auto-completion, inline documentation, etc.
我们推荐使用 TypeScript 以获得最佳开发体验——包括自动补全、内联类型文档提示等。
You do not need to use TypeScript to use PostGraphile, but if you do then you
must use a version from TypeScript v5.0.0 upward and configure it to support
the exports property in package.json, you can do so by adding this to your
TypeScript configuration:
使用 PostGraphile 并不强制要求 TypeScript;但如果你选择使用,则必须使用 TypeScript v5.0.0 及以上版本,并将其配置为支持 package.json 中的 exports 字段。你可以在 TypeScript 配置文件中加入以下设置:
"moduleResolution": "node16", // Or "nodenext"
Instead of configuring TypeScript manually, we recommend that you use the appropriate TSConfig Base for your Node.js version.
相比手动逐项配置 TypeScript,我们建议直接继承与你所用 Node.js 版本相匹配的 TSConfig Base 基础配置。
{
"extends": "@tsconfig/node24/tsconfig.json"
}
If you want to use type stripping (which limits the syntax you can use,
but means Node can run your TS files directly), then also add the
@tsconfig/node-ts preset and make sure you're running Node 24+ and TypeScript
v5.8.0+. To use the LTS version of Node along with type stripping:
如果你希望使用类型剥离(type stripping,它会限制部分可用的 TS 语法,但允许 Node 直接运行 .ts 文件),请同时引入 @tsconfig/node-ts preset,并确保运行环境为 Node 24+ 及 TypeScript v5.8.0+。若要搭配 Node LTS 版本使用类型剥离,可按如下方式配置:
{
"extends": [
"@tsconfig/node-lts/tsconfig.json",
"@tsconfig/node-ts/tsconfig.json"
]
}
Our adherence to semver does not cover types — we may make breaking changes to TypeScript types in patch-level updates. The reason for this is that TypeScript itself is ever-changing, and the libraries we depend on often make breaking type changes, forcing us to do so too. Further, improvements to types are generally a good thing for developer experience, even if it might mean you have to spend a couple minutes after updating to address any issues.
我们对 semver 语义化版本规范的遵循不包含类型定义——我们可能在补丁级(patch)更新中对 TypeScript 类型做出破坏性调整。原因在于 TypeScript 本身仍在持续演进,且我们所依赖的第三方库也常会进行破坏性的类型改动,从而使我们不得不随之调整。此外,类型定义的改进总体上有助于提升开发体验,即便升级后可能需要花几分钟微调代码以适配类型报错。
However, we try and keep the TypeScript types as stable as possible, only making breaking changes when their benefits outweigh the costs (as determined by our maintainer), and we do our best to detail in the release notes how to deal with these changes (if any action is necessary).
不过,我们会尽量保持 TypeScript 类型的稳定性,仅在(经维护者评估后)确认收益大于改造成本时才引入破坏性类型变更,并尽可能在发布说明中详细列明迁移处理方法(如果需要手动调整的话)。
Not using TypeScript?不使用 TypeScript?
You do not need to use TypeScript to use PostGraphile, but without it you will
find editors such as VSCode will highlight your import paths with error
notifications. To stop this, you can add the following to jsconfig.json:
即便不使用 TypeScript 也能正常运行 PostGraphile,但如果不加配置,VSCode 等编辑器可能会将部分模块导入路径标红报错。要消除此类提示,可以在 jsconfig.json 中添加以下配置:
{
"compilerOptions": {
"moduleResolution": "node16"
}
}
PostgreSQL: use latestPostgreSQL:建议使用最新版本
For best results we recommend you use the latest stable release of PostgreSQL that we officially support, however PostGraphile should run well on any earlier version of PostgreSQL that has not yet reached end-of life.
为获得最佳效果,建议使用我们官方支持的最新稳定版 PostgreSQL;不过对于尚未结束生命周期(EOL)的较早 PostgreSQL 版本,PostGraphile 通常也能稳定运行。
Once a PostgreSQL version reaches end-of-life we no longer support it, and any future patch release may be incompatible with it. We do not see this as a violation of semver — once a PostgreSQL version reaches EOL no reasonable user should use it, and as such a change to drop support for it is not a breaking change for reasonable users.
一旦某个 PostgreSQL 版本到达生命周期终点(EOL),我们将不再提供支持,后续任意补丁版本都可能不再兼容该版本。我们不认为这违背了 semver 语义化版本规范——当某个 PostgreSQL 版本进入 EOL 后,正常情况下已不应继续使用它,因此移除对其的支持对合理使用环境而言并不构成破坏性变更。
Currently versions 12 and 13 are EOL according to the PostgreSQL project. They work with PostGraphile and are exercised in CI at time of writing; however, they are not officially supported and may be removed from CI if they hold us back.
目前按照 PostgreSQL 官方项目的支持周期,12 和 13 版本均已进入 EOL。截至本文撰写时,它们仍可与 PostGraphile 配合使用并在 CI 中进行测试,但已不再属于官方支持范围;一旦影响后续开发演进,它们可能会随时从 CI 中移除。
PG 12 [unsupported - EOL Nov 2024]PG 12 [非官方支持 - 已于 2024 年 11 月 EOL]
Works well; but not officially supported and support may be dropped in a patch release.
运行正常;但已不再受官方支持,且可能在后续补丁版本中移除兼容。
PG 13 [unsupported - EOL Nov 2025]PG 13 [非官方支持 - 已于 2025 年 11 月 EOL]
Works well; but not officially supported and support may be dropped in a patch release.
运行正常;但已不再受官方支持,且可能在后续补丁版本中移除兼容。
PG 14 [officially supported]PG 14 [官方支持]
Works well.
运行正常。
PG 15 [officially supported]PG 15 [官方支持]
Works well.
运行正常。
PG 16 [officially supported]PG 16 [官方支持]
Works well.
运行正常。
PG 17 [officially supported]PG 17 [官方支持]
Works well.
运行正常。
PG 18 [officially supported]PG 18 [官方支持]
Works well.
运行正常。
Operating system操作系统
PostGraphile is developed on *nix operating systems like GNU/Linux and macOS. As far as we know it works on Windows, but since no-one in the core team uses Windows for development our Windows support is "best effort" rather than "officially supported" — please file an issue if you have problems, but we may be asking for your help to fix/test them!
PostGraphile 主要在 GNU/Linux 和 macOS 等 *nix 操作系统上开发。据我们所知它在 Windows 上也可正常运行,但由于核心团队成员均不使用 Windows 进行开发,我们对 Windows 的支持属于“尽力而为(best effort)”而非“官方正式支持”——如遇问题欢迎提交 issue,但在排查修复和测试时可能需要你的协助!