Version 5 New Feature SummaryVersion 5 新特性概览
One of the main aims for PostGraphile V5 was to replace the cumbersome "lookahead engine" with something much more pleasant and powerful. After many iterations, we ultimately invented Grafast: a new planning and execution engine for GraphQL.
PostGraphile V5 的主要目标之一,就是用一套更优雅、更强大的机制取代繁琐的“lookahead 引擎”。经过多轮迭代,我们最终打造出了 Grafast:一套全新的 GraphQL 规划与执行引擎。
Since the lookahead system underpinned everything in Version 4 of PostGraphile, replacing it meant rebuilding everything from the ground up, so we took the opportunity to fix a huge number of other snags and suboptimal experiences in Version 4 — also adding in many capabilities which weren't possible, and changing some of the default behaviors.
由于 lookahead 系统是 PostGraphile V4 一切机制的基石,替换它意味着必须从头重构整个底层架构。我们也借此契机修复了 V4 中大量的痛点与不佳体验,新增了许多过去无法实现的能力,并优化调整了部分默认行为。
Ultimately, Version 5 brings a number of new paradigms to PostGraphile, and along with that many new features. The following list is a summary of those new features but is by no means complete!
最终,V5 为 PostGraphile 带来了诸多全新范式与大量新特性。下文汇总了其中的主要亮点(远非全部清单)!
Features new to Version 5V5 新增特性
-
Lookahead replaced by advanced GraphQL query planning via new Grafast engine
由全新的 Grafast 引擎提供高级 GraphQL 查询规划,彻底取代原有的 lookahead 机制
Every GraphQL request can get an associated plan diagram to ease understanding and debugging每个 GraphQL 请求都能生成对应的执行计划图(plan diagram),便于理解流程与排查调试
An autogenerated Grafast plan diagram for the displayed GraphQL query. Plan diagrams detail the steps required to complete a GraphQL request and show how the data flows between them. See "Plan Diagrams" in the Grafast documentation for more details.针对所示 GraphQL 查询自动生成的 Grafast 执行计划图。该图详细展示了完成一次 GraphQL 请求所需的各个 step,以及数据在 step 之间的流转路径。更多细节请参阅 Grafast 文档中的 “Plan Diagrams”。
Massively improved SQL query generation: smaller, simpler, easier to understand, more performant大幅优化的 SQL 生成能力:语句更精简、结构更清晰、更易于理解,性能也更出色
An example of the vast improvement in the autogenerated SQL queries in Version 5 as compared to Version 4 for the same query. Generated SQL is now easier to understand and debug, and the V5 SQL query shown is twice as fast as the V4 SQL query.同一查询在 V5 与 V4 中自动生成 SQL 语句的对比示例。V5 生成的 SQL 不仅更易读、更方便调试,而且示例中 V5 SQL 的执行速度达到了 V4 的两倍。
-
Ability to cache certain SQL queries [experimental]
支持缓存特定 SQL 查询(实验性)
-
Polymorphism support, both in the engine and for Postgres autogeneration
引擎层与 Postgres 自动生成层均提供多态(Polymorphism)支持
-
Incremental delivery support [experimental] - now possible to use
@streamand@defer增量传输支持(实验性)——现已可以使用
@stream和@defer-
In addition to improving page load times by delaying delivery of expensive fields, this can be used to unlock previously impossible use cases - e.g. streaming huge amounts of data (e.g. to generate CSVs from reporting or similar)
除了能通过延迟返回耗时字段来缩短页面加载时间外,这还解锁了过去无法实现的场景——例如流式传输海量数据(如从报表接口导出大型 CSV 文件)
-
-
New "behavior" system allows more precise control over how schema is generated
全新 “behavior(行为)”系统让 schema 生成的控制粒度更加精准
-
Massively reduces the need for manually removing fields from the schema
大幅减少从 schema 中手动移除字段的需求
-
-
Significantly reduced load on PostgreSQL database
显著降低 PostgreSQL 数据库的负载压力
Connections are now as cheap as lists unless using connection-specific features (which are also cheaper)除非使用 Connection 专属特性(即便使用,其开销也已大幅降低),否则 Connection 的查询开销现已与普通列表完全持平
-
Thanks to new planning system, "hasNextPage" / "hasPreviousPage" can be achieved by just fetching an extra row
得益于全新的规划系统,只需多查询一行数据即可算出
hasNextPage/hasPreviousPage -
Cursors are much cheaper
cursor 的生成与计算开销大幅降低
Export your schema as executable code [experimental]将 schema 导出为可执行代码(实验性)
Great for serverless:
非常适合 Serverless 环境:
-
no run-time introspection
无需运行时 introspection
-
fewer dependencies
更少的依赖项
-
lower memory usage
更低的内存占用
-
near-instant startup (great for serverless)
近乎瞬时的冷启动速度(对 Serverless 极为友好)
Also helps with understanding how the system/plans/etc works; and enables a path to migrate away from auto-generated should you later want to
此外,导出的代码也有助于理解系统及 plan 的内部运作原理;如果日后希望脱离自动生成方案,它也能为你提供一条平滑的迁移路径
See "Exporting your schema" for more information.
更多详情请参阅 “导出 schema(Exporting your schema)”。
makeExtendSchemaPlugin renamed to extendSchema and massively improvedmakeExtendSchemaPlugin 更名为 extendSchema,功能全面增强
makeExtendSchemaPlugin 更名为 extendSchema,功能全面增强No more selectGraphQLResultFromTable, @requires, @pgQuery or other hacks to abstract away the complicated lookahead system. Instead, use straightforward declarative code for all these concerns, integrating deeply and automatically with the Grafast operation plan
不再需要 selectGraphQLResultFromTable、@requires、@pgQuery 等各类变通手段来规避复杂的 lookahead 系统。如今只需用直观的声明式代码即可解决这些问题,并与 Grafast 操作计划自动深度集成
Extending auto-generated types should always work, independent of plugin order
扩展自动生成的类型始终可靠生效,不再受插件注册顺序的影响
User data and Postgres leaf data (e.g. column values) can be used interchangeably and the planning system will automatically optimize Postgres data (via inlining) if it can
自定义数据与 Postgres 叶子数据(如表列值)可以互换使用,只要条件允许,规划系统会自动通过内联来优化 Postgres 数据的读取
-
Much easier to add "computed columns" in user code, which significantly increases performance by not having Postgres do this work
在应用层代码中添加“计算列”变得前所未有地简单,无需让 Postgres 承担这类计算开销,从而显著提升性能
-
Even if you query remote data sources (e.g. Stripe) in fields within a list, when you come back to postgres everything is automatically re-batched so no introduction of N+1 problem
即便在列表字段中先请求了远程数据源(如 Stripe),随后再回到 Postgres 查询关联数据时,系统仍会自动重新合批(re-batch),彻底杜绝 N+1 问题
-
Unified plugins: no "server plugins" vs "schema plugins" any more
统一的插件模型:不再区分“server 插件”与“schema 插件”
-
Presets: easily share plugin lists and configuration options between servers, and still perform local customization easily
Preset(预设配置):轻松在多个服务间共享插件列表与配置项,同时仍能便捷地进行本地微调
-
Consolidated configuration across CLI, library and schema-only usage; no more postgraphilerc.
统一的配置体系:覆盖 CLI、库模式与纯 schema 模式,告别
postgraphilerc。
Generate personalized documentation based on which plugins/presets you're using可根据当前启用的插件和 preset 生成专属配置文档
graphile config options showing the options available to be set inside the config file.执行 graphile config options 后输出的部分彩色 Markdown 截图,展示了配置文件中可设置的各项选项。
graphile inflection list command, including a summary of the available inflectors and their arguments.graphile inflection list 命令初始输出的截图,列出了可用 inflector 及其参数的摘要信息。
graphile inflection list command, detailing each inflector, its documentation and its rough TypeScript definition.graphile inflection list 命令输出下文部分的截图,详细展示了每个 inflector 的说明文档及其大致的 TypeScript 类型定义。graphile config print showing the options that the local configuration file is using.执行 graphile config print 后输出的部分彩色截图,展示了当前本地配置文件实际生效的各项选项。(More to come!)
(更多命令敬请期待!)
-
Better Relay support via
postgraphile/presets/relay通过
postgraphile/presets/relay提供更完善的 Relay 支持 -
Massively enhanced TypeScript support
大幅增强的 TypeScript 类型支持
-
Fully implements the latest GraphQL-over-HTTP specification draft
完整实现最新的 GraphQL-over-HTTP 规范草案
-
Ability to perform JOINs in SQL
支持在生成的 SQL 中执行 JOIN 联表查询
-
No
RETURNING *on mutations, so column-level select grants don't break mutationsmutation 不再使用
RETURNING *,因此列级SELECT权限控制不会再导致 mutation 报错 -
Write-only columns now supported in mutations
mutation 现已支持只写列(write-only column)
Use separate transactions in the same GraphQL request支持在同一个 GraphQL 请求中使用多个独立事务
Parts of mutations can now use a connection string with elevated privileges without transaction isolation causing these changes to not be reflected in the mutation payload
mutation 的部分阶段现在可以使用高权限连接字符串执行操作,且不会因事务隔离性导致这些变更无法反映在最终的 mutation payload 中
Massive enhancements to no-ignore-indexes大幅增强的 no-ignore-indexes 索引检查策略
no-ignore-indexes 索引检查策略Including ability to overrule, and only preventing the expensive backwards relations whilst still allowing the cheap forwards relations.
支持按需覆盖默认限制,并且只拦截高开销的反向 relation,同时保留低开销的正向 relation。
Bespoke support for major Node.js web frameworks, fitting naturally into each of their workflows为各大主流 Node.js Web 框架提供深度定制适配,自然融入各自的工作流
Even makes use of things like vendor-specific websocket modules (e.g. @fastify/websocket or koa-websocket) for deeply integrated websocket support
甚至能够利用各框架原生的 WebSocket 扩展模块(如 @fastify/websocket 或 koa-websocket),实现深度集成的 WebSocket 支持
-
Theoretically easier to use with other GraphQL servers (assuming that they allow you to replace the 'execute' method)
理论上更易于集成到其他 GraphQL 服务端框架中(只要它们允许替换底层的
execute方法) -
Multiple (postgres) databases in same GraphQL schema
支持在同一个 GraphQL schema 中接入多个 Postgres 数据库
New strongly typed PostgreSQL introspection library pg-introspection全新强类型 PostgreSQL introspection 库 pg-introspection
pg-introspection全新强类型 PostgreSQL introspection 库 pg-introspectionNow generated from Postgres documentation and strongly typed (view postgres docs when hovering an introspection value in your editor!), plus much simpler so should work better with other postgres-alikes 🤞
现已基于 Postgres 官方文档自动生成并具备完整强类型(在编辑器中鼠标悬停于 introspection 字段即可查看对应 Postgres 文档!);结构也更加简洁,理论上能更好地兼容各类 Postgres 衍生数据库 🤞
-
Optionally define your resources (tables, functions, views, etc) manually and generate the schema from them (enables generation from DDL or model objects)
支持手动定义 resource(表、函数、视图等)并据此生成 schema(从而可基于 DDL 或代码模型对象自动建图)
-
Better capabilities for allowing changes to your underlying Postgres tables without causing breaking changes to GraphQL API
提供更完善的能力,允许在不破坏现有 GraphQL API 兼容性的前提下调整底层 Postgres 表结构
-
Use your choice of Postgres client
可自由选用任意偏好的 Postgres 客户端库
-
Change your PostgreSQL connection string at runtime (assuming you have multiple identical databases - sometimes used for multi-tenancy)
支持在运行时动态切换 PostgreSQL 连接字符串(适用于拥有多个同构数据库的场景,例如多租户架构)
-
Optionally use alternative authorization techniques (don't need to use RLS) [experimental]
支持按需采用替代鉴权方式,无需强制依赖 RLS(实验性)
-
Better support for various Postgres types
对各类 Postgres 数据类型提供更完善的支持
-
Don't convert unknown types to
String, instead omit them不再将未知类型强行降级为
String,而是直接忽略它们 -
In graphile-build, GraphQL types are registered at "init" time, so
build.getTypeByNameno longer affected by plugin ordering concerns在
graphile-build中,GraphQL 类型统一在 “init” 阶段注册,因此build.getTypeByName不再受插件加载顺序影响 -
Various other plugin ordering issues eliminated or reduced
消除或大幅减少了其他各类插件顺序依赖问题
-
Overhauled inflection system: more consistent, simpler to achieve common tasks
全面重构的命名推导(inflection)系统:规则更一致,常见定制任务实现起来更简单
-
Use
sqldirectly for making SQL fragments, rather than needingsql.fragment(reduces code verbosity)直接使用
sql即可构建 SQL 片段,无需再写冗长的sql.fragment(有效精简代码量) -
GraphQL v16 support
支持 GraphQL v16
-
Planning information stored directly into GraphQL schema objects - removing a field now removes all its behaviors (re-introducing a field with the same name will not cause problems like it did in V4)
规划信息现在直接存储在 GraphQL schema 对象内部——移除字段时其所有 behavior 都会一并移除(后续重新引入同名字段时,也不会像 V4 那样产生冲突问题)



