PostGraphile IntroductionPostGraphile 简介
Coming from PostGraphile Version 4? Check out the migration guide!
正在从 PostGraphile V4 升级?请查看迁移指南!
If you already use PostgreSQL then you understand the value that a strongly typed and well defined schema can bring to application development; GraphQL is the perfect match for this technology when it comes to making your data layer accessible to your frontend application developers (or even API clients).
如果你已经在用 PostgreSQL,一定深知强类型、结构清晰的数据库 schema 对应用开发的价值。而在把数据层开放给前端开发者乃至各类 API 客户端时,GraphQL 恰好是它的绝佳搭档。
PostGraphile uses automation and intelligent defaults to eradicate the time consuming and repetitive parts of building a best practices GraphQL API, whilst giving you the tools you need to customize and extend your schema to be exactly what you need. And because it’s powered by Grafast it’s extremely unlikely that you’d be able to build a GraphQL API using traditional GraphQL/DataLoader patterns that’s anywhere near as fast as a PostGraphile API — it truly runs rings around traditional API development practices.
PostGraphile 通过自动化机制与智能默认配置,帮你省去构建符合最佳实践的 GraphQL API 时那些耗时且重复的样板工作,同时提供完善的工具让你按需定制和扩展 GraphQL schema。底层得益于 Grafast 引擎,传统 GraphQL 搭配 DataLoader 的手写方案在性能上几乎难以望其项背——PostGraphile 在开发效率与运行性能上都远远领先于传统模式。
Built on a plugin system, you can easily pick and choose the features that you want in your API (and even develop your own or mix in features from the community). Using the smart tags system you can easily tweak which entities appear, and how they’re exposed. If you ultimately decide an auto-generated GraphQL API may not be for you, PostGraphile has an ‘export’ feature so your generated API can be exported as executable JavaScript code which you can then maintain yourself ─ there's no lock-in.
基于灵活的插件系统,你可以自由挑选 API 所需的功能,也可以自行编写或直接引入社区插件。借助 smart tags 系统,能轻松控制哪些数据库实体暴露到 API 中以及如何暴露。即便将来你不再希望完全依赖自动生成,PostGraphile 还提供“导出”功能,可将生成的 API 导出为可独立维护的 JavaScript 代码,彻底摆脱框架锁定。
PostGraphile doesn't have to be (and generally should not be) a “1-to-1 map” of your database.
PostGraphile 没必要(通常也不应该)做成数据库结构的“1 对 1 镜像”。
Whilst its common for a significant portion of your data model to remain broadly aligned from database through to frontend, that's not true of every resource. Thus, PostGraphile gives you a wide array of tools and techniques to sculpt your schema to fit frontend needs, whilst still eliminating unnecessary work for the parts of your data model that are standard and consistent throughout the stack.
尽管大多数数据模型从数据库到前端往往保持一致,但并非所有资源都如此。因此,PostGraphile 一方面替你自动处理前后端通用、标准化的模型部分,免去重复劳动;另一方面也提供了丰富的手段,让你精细雕琢 GraphQL schema 以贴合前端真实诉求。
PostGraphile automatically reflects the permissions in your database and only exposes the tables, columns, functions and mutations that are granted to it.
PostGraphile 会自动映射数据库中的权限设置,仅暴露已授予访问权限的表、列、函数及相应的 mutation。
Smart tags and similar techniques allow you to hone the GraphQL schema to your needs: hide or exposing tables/columns/functions, change their naming or presentation, indicate abstract types/polymorphism, or otherwise manipulate the generated schema with simple tagging.
通过 smart tags 等机制,你可以用简单的标签来打磨 GraphQL schema:隐藏或暴露表、列与函数,调整命名和呈现形式,声明抽象类型与多态关系,或者对生成的 schema 做各种精细微调。
With schema extensions, you can add any types/fields/args that you need to, which can communicate with any data source that Node itself can communicate with. You can also use the plugin interface to wrap plan resolvers with your own logic, which gives huge control over authorization, presentation, filtering, and various other topics.
利用 schema 扩展能力,你可以添加任意自定义类型、字段和参数,并对接 Node.js 能访问的任何外部数据源。你还可以通过插件接口包装执行计划函数(plan resolver),注入自定义逻辑,从而在鉴权、数据呈现、过滤等方面获得极高的掌控力。
By exporting the executable schema, you can see the plan resolvers/types/fields that PostGraphile has generated for you and, should you choose to, you can take this code and make it your own — either for the entire schema, or for specific portions of it. This can be used to enable you to evolve your database tables without breaking your GraphQL schema.
导出可执行的 schema 代码后,你可以直接查看 PostGraphile 生成的 plan resolver、类型和字段,并按需接管整个 schema 或其中的局部代码。这样一来,即使底层数据库表结构演进,也能确保对外暴露的 GraphQL schema 保持向后兼容。
We strongly advise that you start with as small a GraphQL API as you can, and then add features to it as you need them, rather than going for a “kitchen sink” approach!
我们强烈建议从尽量精简的 GraphQL API 起步,按业务演进逐步增补功能,避免一开始就把所有能力一股脑全盘暴露。
If your company needs a GraphQL API and the data the API serves comes mostly (but not exclusively!) from PostgreSQL databases then PostGraphile can help you craft your perfect GraphQL API in a matter of days, if not hours; saving you weeks if not months of development time.
如果你们的业务需要一个 GraphQL API,且主要数据(不局限于此)存放在 PostgreSQL 中,PostGraphile 能在几天甚至几小时内帮你搭建出理想的 GraphQL API,省下数周乃至数月的研发投入。
For databases that already use row-level security you might be able to build a secure, performant and extensible GraphQL API in mere minutes. We still recommend that you take some time to hone your API though!
如果数据库已经启用了行级安全策略(RLS),你甚至几分钟内就能搭出一个安全、高性能且可扩展的 GraphQL API——不过我们仍建议花点时间细心打磨对外接口。
If you are new to GraphQL we recommend you read through the official introduction to GraphQL here before continuing through the PostGraphile documentation.
如果你刚接触 GraphQL,建议先阅读GraphQL 官方入门教程,再继续深入 PostGraphile 文档。
Some of the features we offer:
PostGraphile 的部分核心特性:
-
Incredible performance - even for your custom logic!
卓越的运行性能——即便包含自定义逻辑也毫不逊色!
-
Full GraphQL feature-set, including advanced topics such as:
完整支持 GraphQL 特性集,涵盖如下高阶能力:
-
polymorphism (interfaces and unions)
多态(
interface接口与union联合类型) -
@stream/@defersupport支持
@stream/@defer增量传输指令
-
-
Excellent Relay support via our
postgraphile/presets/relaypreset:通过
postgraphile/presets/relay预设提供一流的 Relay 支持:-
Global object identification
全局对象唯一标识(
Node接口) -
Cursor pagination
基于游标(
cursor)的分页 -
Mutation input objects and payloads
规范的
Mutationinput输入对象与payload返回结构
-
-
Massively reduced load on your database without the complexity of caching/cache invalidation
显著降低数据库负载,无需引入复杂的多层缓存与缓存失效难题
-
Integrates with any authentication middleware available in Node
可无缝集成 Node.js 生态中的任意鉴权中间件
-
Easily add fields and mutations via JS/TS plugins or database functions
-
Written in pure TypeScript - no binary modules!
纯 TypeScript 编写,无任何原生二进制模块依赖!
-
Very fast startup in serverless
在 Serverless 环境中启动极快
-
Bring your own PostgreSQL driver/adaptor (integrate with almost any Postgres client library)
可自由搭配 PostgreSQL 驱动/适配器(几乎兼容任意 Postgres 客户端库)
-
Run as a CLI, as a Node.js middleware, or a standalone GraphQL schema
支持以 CLI 命令行、Node.js 中间件或独立 GraphQL schema 等多种方式运行
-
Easy customization via smart tags
通过 smart tags 轻松定制
-
Automatic CRUD mutations e.g.
updatePost自动生成 CRUD mutation,例如
updatePost -
Almost all features are optional, and most can be customized on a per-table, per-column or per-constraint basis (as appropriate)
几乎所有特性均为按需可选,且大多数支持在表、列或约束粒度上单独定制
-
Incredible versatility via a wide array of plugins:
依托丰富的插件生态实现极高的扩展性:
-
Aggregates
聚合查询(Aggregates)
-
Powerful filtering
强大的条件过滤
-
Soft deletion
软删除(Soft deletion)
-
Upsert
插入或更新(Upsert)
-
Many-to-many navigation
多对多关联导航
-
Ordering by related tables
按关联表字段排序
-
Multi-tenancy
多租户支持
-
PostGIS (not yet ported to V5)
PostGIS(暂未移植到 V5)
-
And many many more...
以及更多其他能力……
-
The easiest way to get started is with the CLI interface; if you
have npx installed you can try it out with:
最快上手的方式是使用 CLI 命令行工具;只要本地装有 npx,就可以直接执行以下命令体验:
npx pgl -P pgl/amber -e -c 'postgres:///mydb'
(Replace the connection string with a PostgreSQL connection string to your
database. If your data is not located in the public schema of your database
you can specify a comma-separated list of database schemas with -s a,b,c.)
(请将上述连接字符串替换为你的 PostgreSQL 数据库连接地址。如果数据不在数据库的 public schema 中,可通过 -s a,b,c 指定以逗号分隔的数据库 schema 列表。)