PostgRPC

直接使用gRPC、gRPC-web或转码JSON查询Postgres数据库

目录

1. 简介
   1. 原因
   2. 类似项目
   3. 目标
   4. 非目标
2. 入门
   1. 安装
   2. 配置
   3. 使用
3. 示例
   1. JSON转码
   2. gRPC-web
   3. 负载均衡
   4. 认证
4. 常见问题解答
5. 路线图

简介

为什么？

有时候你想使用Postgres数据库的全部功能，但无法直接连接，或者不想编写一个包装数据库查询的自定义API服务。PostgRPC为你提供了通过gRPC或JSON使用SQL的权力，代表你处理分布式事务和连接管理。

类似项目

PostgRPC与优秀的PostgREST和PostGraphile项目类似。与这些项目不同，PostgRPC允许你直接使用SQL，而不是将接口包装在另一种查询语言中（即REST DSL或GraphQL）。此外，PostgRPC允许你通过查询数据库时使用的相同gRPC或JSON接口与较低级别的数据库结构（如事务）进行交互。

目标

• 性能：在持久连接上运行查询始终是最佳选择，但使用PostgRPC应该是次佳选择。当需要并发查询并且这些查询的扩展速度超过连接时，PostgRPC应该能处理比任何基于直接连接的连接池解决方案更多的并发查询请求。
• 原始关注点：Postgres具有的功能，PostgRPC应通过查询接口支持该功能。当这不可能时，PostgRPC应努力提供分布式等效功能。
• 易用性：希望开始使用PostgRPC的人应该能够在各种系统上快速将其作为服务启动。PostgRPC应包含大多数用例的合理默认值。对于更有限的情况，PostgRPC应通过功能门控和条件编译轻松配置。
• 类型推断：PostgRPC应适应JSON在输入和输出中的灵活性，而不是将JSON或gRPC类型映射到Postgres类型。这包括尽可能利用Postgres内置的类型推断。
• 定制：PostgRPC提供的二进制文件应该是gRPC服务的参考实现。对于那些需要更多灵活性的人，提供了postgrpc库来处理自定义连接池逻辑。

非目标

• 认证：PostgRPC不包括Postgres数据库本身提供的认证或授权机制之外的其他机制。可以通过X-Postgres-Role头（当启用role-header功能时）设置Postgres的ROLE，正确推导该头的值是其他更适合这项任务的服务的责任（例如，Ory Oathkeeper）
• 严格请求类型：PostgRPC将尽可能使用输入值的二进制编码。当参数的二进制编码不明显时，PostgRPC将使用文本编码来利用Postgres的内置类型推断。所有输出都仅以与JSON兼容的动态类型进行解码，不尝试使用更严格的Postgres类型。
• 一体化：PostgRPC不会替换您的应用堆栈。相反，PostgRPC是一把易于集成到包含用户管理、负载均衡和从公共端点路由流量等工具的工具。除非您知道自己在做什么（即使在那时，也请考虑在examples目录中找到的替代方案），否则不要通过PostgRPC公开数据库。

入门

安装

对于二进制安装，使用cargo install postgrpc。可以使用--features自定义postgrpc可执行文件的编译。

对于库安装，在cargo管理的Rust项目中使用cargo add postgrpc。

配置

可以使用以下环境变量配置postgrpc可执行文件

• HOST：postgrpc服务使用的宿主。默认为127.0.0.1。
• PORT：postgrpc服务使用的端口。默认为50051。
• TERMINATION_PERIOD：在SIGTERM信号关闭前，postgrpc等待的毫秒数。postgrpc会优雅地关闭，尽可能等待请求完成。此值对于等待像envoy这样的代理排空很有用，允许postgrpc在小于TERMINATION_PERIOD毫秒的情况下无错误地处理这些请求。

此外，默认连接池可以使用以下环境变量进行配置

• MAX_CONNECTION_POOL_SIZE：池允许保留的上游数据库连接数。默认为主机机器上可用的CPU数量的4倍。
• STATEMENT_TIMEOUT：postgrpc等待放弃查询的毫秒数。
• RECYCLING_METHOD：当连接返回到连接池时运行的回收方法。默认为clean。
• PGDBNAME（必需）：要连接的Postgres数据库的名称。
• PGHOST：要连接的Postgres集群的主机。默认为localhost。
• PGPASSWORD（必需）：连接到Postgres数据库时使用的用户密码。
• PGPORT：要连接的Postgres集群的端口。默认为5432。
• PGUSER（必需）：连接到Postgres数据库时使用的用户。
• PGAPPNAME：连接到Postgres数据库时使用的应用程序标签。默认为postgrpc。
• PGSSLMODE：连接到Postgres数据库时使用的sslmode。支持的值有disable、prefer和require。

使用

当PostgRPC在默认端口和主机上运行时，可以使用grpcurl来查询数据库

grpcurl \
  -plaintext \
  -d '{"statement":"select 1 + 1 as two"}' \
  [::]:50051 postgres.Postgres/Query

# { "two": 2 }

要使用与最初连接数据库不同的（已存在的）ROLE，请使用X-Postgres-Role头

grpcurl \
  -plaintext \
  -d '{"statement":"select current_user"}' \
  -H 'X-Postgres-Role: my-other-user' \
  [::]:50051 postgres.Postgres/Query

# { "current_user": "my-other-user" }

示例

所有示例都可以在./examples目录中使用docker-compose运行。点击下面的链接了解每个示例的更多信息。

• JSON转码
• 负载均衡
• 认证

常见问题解答

1. 谁构建了PostgRPC？ Platter团队。
2. PostgRPC准备好投入生产了吗？ PostgRPC应被视为alpha级软件，不提供任何保证或暗示。如果您仍然想自己运行PostgRPC，请确保将其作为包括强大身份验证和授权的堆栈的一部分运行，并确保您使Postgres数据库免受恶意查询的攻击！但您已经在做这样的事情，对吧？
3. 如何发音PostgRPC？ "post-ger-puck"

贡献

欢迎以错误报告、功能请求、软件修复和文档更新等形式做出贡献。请通过GitHub提交所有代码贡献作为pull请求。

路线图

• 无需额外代理即可进行本地JSON转码
• LISTEN/NOTIFY基于的通道
• MATERIALIZED VIEW基于的更新流
• 显式查询注册和编译时gRPC兼容的proto生成，作为动态Query接口的替代方案

相关Crates

Postguard