Skip to main content

PresetsPreset(预设配置)

PostGraphile ships a small set of presets that are designed to be composed; pick the foundational crystal preset that matches your starting point, and layer feature presets as needed.

PostGraphile 内置了一组精简、可组合的 preset;先挑选符合项目起点的基础“水晶(crystal)”preset,再按需叠加各类功能 preset 即可。

The "amber" preset“amber” 预设(preset)​

graphile.config.ts
import { PostGraphileAmberPreset } from "postgraphile/presets/amber";

const preset: GraphileConfig.Preset = {
extends: [PostGraphileAmberPreset],
/* ... */
};
export default preset;

Amber is the current baseline preset. It wires in the Graphile Build and Graphile Build PG default plugin lists and sensible options and inflection for new PostGraphile users. Every production schema should include Amber either directly or transitively.

Amber 是当前的基准 preset,它集成了 Graphile Build 与 Graphile Build PG 的默认插件列表,并为 PostGraphile 新用户提供了合理的默认选项及命名推导(inflection)规则。所有生产环境的 GraphQL schema 都应当直接或间接地引入 Amber。

The "v4" compatibility preset“v4” 兼容预设(preset)​

graphile.config.ts
import { makeV4Preset } from "postgraphile/presets/v4";

const preset: GraphileConfig.Preset = {
extends: [
makeV4Preset({
/* Insert your PostGraphile V4 configuration options here */
}),
],
/* ... */
};
export default preset;

makeV4Preset() extends Amber and restores many PostGraphile V4 behaviours and inflection rules. Use it when upgrading an existing V4 project so that the generated schema and runtime defaults stay aligned with what your clients already expect. The V4 migration docs cover this path in more detail.

makeV4Preset() 基于 Amber 扩展而来,还原了 PostGraphile V4 的诸多 behavior 与 inflection 规则。升级现有 V4 项目时建议使用它,以确保生成的 schema 和运行时默认行为仍符合客户端原有预期。更多细节请参阅 V4 迁移文档。

The "Relay" preset“Relay” 预设(preset)​

graphile.config.ts
import { PostGraphileRelayPreset } from "postgraphile/presets/relay";
import { PostGraphileAmberPreset } from "postgraphile/presets/amber";

const preset: GraphileConfig.Preset = {
extends: [PostGraphileAmberPreset, PostGraphileRelayPreset],
/* ... */
};
export default preset;

PostGraphileRelayPreset layers additional behaviours on top of your existing foundation to produce a Relay-focussed schema. It prefers connections over lists, hides primary-key columns that are surfaced via nodeId, and adjusts inflection so that id fields follow Relay conventions. Combine it with Amber or another foundational preset. The preset is currently marked experimental, so expect refinements between releases.

PostGraphileRelayPreset 会在现有基础 preset 之上叠加额外 behavior,以生成面向 Relay 的 schema:优先使用 Connection 而非普通列表,隐藏已通过 nodeId 暴露的主键列,并调整 inflection 使 id 字段遵循 Relay 规范。请将其与 Amber 或其他基础 preset 配合使用。该 preset 目前仍处于实验阶段,后续版本可能会继续调整细节。

Where did my fields go?我的字段去哪儿了?

The Relay preset tries to do away with primary key fields and fields that reference them as much as possible, opting instead for using the Node ID in as many places as possible. If you're coming from V4, probably stick with the v4 preset unless you really want to make some significant changes to your schema.

Relay preset 会尽量移除主键字段以及引用主键的字段,改为尽可能统一使用 Node ID。如果你是从 V4 升级过来的,除非确实打算对 schema 做大幅调整,否则通常更建议继续使用 v4 preset。

The "Lazy JWT" preset“Lazy JWT” 预设(preset)​

graphile.config.ts
import { PgLazyJWTPreset } from "postgraphile/presets/lazy-jwt";
import { PostGraphileAmberPreset } from "postgraphile/presets/amber";

const preset: GraphileConfig.Preset = {
extends: [PostGraphileAmberPreset, PgLazyJWTPreset],
/* ... */
};
export default preset;

PgLazyJWTPreset enables a convenience flow that verifies bearer JWTs inside Grafserv requests and populates pgSettings from the claims. It relies on the Grafserv adaptor (such as grafserv/node) and is intentionally limited; use your own preset.grafast.context if you need finer-grained control. Remember to extend Amber alongside it. For guidance on managing JWTs yourself, see the JWT guide.

PgLazyJWTPreset 提供了一套便捷的认证流程,可在 Grafserv 请求中自动校验 Bearer JWT 并根据其中的 claims 填充 pgSettings。它依赖具体的 Grafserv 适配器(例如 grafserv/node),且功能上故意保持精简;若需更精细的控制,请改用自定义的 preset.grafast.context。使用时别忘了同时继承 Amber。如需了解如何自行管理 JWT,请参阅 JWT 指南。

The "Minify schema" preset“Minify schema” 精简预设(preset)​

graphile.config.ts
import { PgMinifySchemaPreset } from "postgraphile/presets/minify";
import { PostGraphileAmberPreset } from "postgraphile/presets/amber";

const preset: GraphileConfig.Preset = {
extends: [PostGraphileAmberPreset, PgMinifySchemaPreset],
/* ... */
};
export default preset;

PgMinifySchemaPreset is an experimental preset that aims to reduce the schema size for production usage when exporting the schema, to allow for minification of the bundle size in serverless environments such as AWS Lambda. It does so through destructive minification: it strips schema descriptions and deprecations, and reduces registry metadata.

PgMinifySchemaPreset 是一个实验性 preset,旨在导出生产环境使用的 schema 时减小体积,从而缩小在 AWS Lambda 等无服务器环境下的构建产物体积。它采用的是破坏性精简策略:移除 schema 中的描述文本(description)与弃用标记(deprecation),并削减 registry 元数据。

It is not recommended to use this if tooling will be introspecting this schema (for example, GraphiQL or code generation), since the tooling will no longer receive documentation of the schema nor information about deprecated fields; prefer it for production export builds rather than developer-facing schemas where introspection documentation is useful.

如果后续会有工具对该 schema 执行 introspection(例如 GraphiQL 或代码生成工具),则不建议使用此 preset,因为这些工具将无法再获取 schema 文档和字段弃用信息。请仅将其用于生产环境的导出构建,而不要用于面向开发者的 schema(在这类场景下,introspection 文档非常有价值)。

See exporting your schema for guidance.

具体用法请参阅导出你的 schema。

Third-party preset bundles第三方 preset 套件​

Many contrib plugins now publish presets (for example, postgraphile-plugin-connection-filter and @graphile-contrib/pg-many-to-many). These presets generally expose the plugin with some sensible defaults. They do not pull in a foundation preset for you, so include Amber (or whichever crystal preset you started with) before them.

如今许多社区贡献插件(contrib plugin)也会发布配套的 preset(例如 postgraphile-plugin-connection-filter 和 @graphile-contrib/pg-many-to-many)。这些 preset 通常会附带一组合理的默认配置来启用对应插件,但不会自动为你引入基础 preset,因此请在它们之前显式包含 Amber(或你项目起步时选用的其他水晶 preset)。

Stay on your crystal坚守你选定的水晶 preset

We expect to ship more crystal-themed foundational presets over time as the recommended defaults evolve. When you adopt a foundational preset, plan to stay on it for the life of that project unless you explicitly opt into the next crystal. New projects should take whichever foundational preset we recommend at the time; existing projects can continue extending the one they started with.

随着官方推荐默认配置的演进,我们预计未来还会推出更多以水晶命名的基础 preset。一旦选定某个基础 preset,除非你明确决定切换到下一代水晶 preset,否则建议在项目的整个生命周期中都保持使用它。新建项目应选用当下官方推荐的基础 preset,而已有项目则可继续继承当初选定的版本。

Right now there is only one crystal: amber.

目前可用的水晶 preset 只有一个:amber。