pgx

用Rust构建Postgres扩展！

pgx是一个用于在Rust中开发PostgreSQL扩展的框架，并力求在尽可能的方面保持惯用性和安全性。

pgx支持Postgres v11-v15。

欢迎加入我们的Discord服务器。

主要功能

• 一个完全管理的开发环境，包括cargo-pgx
  • cargo pgx new：快速创建新扩展
  • cargo pgx init：安装新的（或注册现有的）PostgreSQL安装
  • cargo pgx run：运行您的扩展并在psql（或pgcli）中进行交互式测试
  • cargo pgx test：跨多个PostgreSQL版本对您的扩展进行单元测试
  • cargo pgx package：为您的扩展创建安装包
  • 更多详情请查看README.md！
• 支持多个Postgres版本
  • 从相同的代码库支持Postgres v11-v15
  • 使用Rust功能门控来使用特定版本的API
  • 无缝测试所有版本
• 自动模式生成
  • 完全使用Rust实现扩展
  • 自动将许多Rust类型映射到PostgreSQL
  • 自动生成SQL模式（或通过cargo pgx schema手动生成）
  • 使用extension_sql!和extension_sql_file!包含自定义SQL
• 安全优先
  • 将Rust的panic!转换为Postgres的ERROR，终止事务而不是进程
  • 内存管理遵循Rust的drop语义，即使在panic!和elog(ERROR)
    的情况下也是如此。
  • 使用#[pg_guard]过程宏来确保上述内容
  • Postgres的Datum是Option<T> where T: FromDatum
    • NULL Datum以安全的方式表示为Option::<T>::None
• 第一类UDF支持
  • 使用#[pg_extern]注解函数以将其暴露给Postgres
  • 对于RETURNS SETOF，返回pgx::iter::SetOfIterator<'a, T>
  • 对于RETURNS TABLE (...)，返回pgx::iter::TableIterator<'a, T>
  • 使用#[pg_trigger]创建触发函数
• 易于自定义类型
  • 使用#[derive(PostgresType)]将Rust结构体用作Postgres类型
    • 默认情况下，在内存/磁盘上以CBOR编码的对象形式表示，并以JSON作为可读格式
    • 提供自定义的内存/磁盘/可读表示
  • 使用#[derive(PostgresEnum)]将Rust枚举用作Postgres枚举
  • 支持使用pgx::composite_type!("Sample")宏进行组合类型
• 服务器编程接口（SPI）
  • 安全访问SPI
  • 从SPI上下文中透明地返回所有权的Datum
• 高级功能
  • 通过pgx::PgMemoryContexts安全访问Postgres的MemoryContext系统
  • Executor/planner/transaction/subtransaction钩子
  • 安全使用Postgres提供的指针，与pgx::PgBox<T>（类似于alloc::boxed::Box<T>）
  • #[pg_guard]宏用于保护需要传递给Postgres的Rust函数中的extern "C"
  • 通过类似于eprintln!的宏访问Postgres的日志系统
  • 通过pgx::pg_sys模块直接访问Postgres内部的大部分内容（不安全操作）
  • 定期添加新功能！

yum install centos-release-scl
yum install devtoolset-7
scl enable devtoolset-7 bash

cargo install --locked cargo-pgx
cargo pgx init

cargo pgx new my_extension
cd my_extension

$ tree 
.
├── Cargo.toml
├── my_extension.control
├── sql
└── src
    └── lib.rs

2 directories, 3 files

cargo pgx run

my_extension=# CREATE EXTENSION my_extension;
CREATE EXTENSION

my_extension=# SELECT hello_my_extension();
 hello_my_extension
---------------------
 Hello, my_extension
(1 row)

cargo install --force --locked cargo-pgx

cargo pgx init

pgx 曾经使用与出色的 time crate 的直接互操作性。然而，由于性能和与 Postgres 精确互操作的问题，现在认为这个特性已被弃用，转而使用低开销的互操作性。您仍然可以通过启用 "time-crate" 功能来请求 TryFrom<time::Type> for pgx::MatchingType 和 From<time::Type> for pgx::MatchingType 的实现。

"unsafe-postgres": 允许为具有不同 ABI 的 Postgres 分支进行编译

截至 Postgres v15，分支允许指定它们使用与规范 Postgres 不同的 ABI。由于 pgx 对 Postgres 内部 ABI 做了无数假设，因此它无法保证编译的 pgx 扩展可以在这样的 Postgres 分支中执行。您，尊敬的编译器运行者，可以通过指定 unsafe-postgres 功能标志来自行保证这一点。否则，pgx 扩展将无法编译并出现类似于的错误

error[E0080]: evaluation of constant value failed
   --> pgx/src/lib.rs:151:5
    |
151 | /     assert!(
152 | |         same_slice(pg_sys::FMGR_ABI_EXTRA, b"xPostgreSQL\0"),
153 | |         "Unsupported Postgres ABI. Perhaps you need `--features unsafe-postgres`?",
154 | |     );
    | |_____^ the evaluated program panicked at 'Unsupported Postgres ABI. Perhaps you need `--features unsafe-postgres`?', pgx/src/lib.rs:151:5
    |

贡献

我们绝对欢迎任何形式的贡献。错误报告、功能请求、文档，甚至 赞助。

如果您想通过拉取请求贡献代码，请将其针对我们的 develop 分支。master 分支旨在表示当前在 crates.io 上的内容。

提供 Postgres 内部的包装器不是一项简单任务，并且完全包装它将花费相当多的时间。现在 pgx 通常已经准备好使用，并且随着时间的推移将继续开发。我们非常感谢您对 pgx 可以做什么的反馈。

黑客攻击

如果您正在对 pgx 进行黑客攻击并希望确保您的测试可以正确运行，您需要将当前 cargo-pgx（您正在工作的修订版）的实现放入您的 PATH。

一种简单的方法是安装 cargo-local-install

cargo install cargo-local-install

然后运行 cargo local-install 以按顶级 Cargo.toml 中指定的方式安装 cargo-pgx。

别忘了将 /path/to/pgx/bin 预先添加到您的 PATH！

此方法还可以用于扩展，以确保使用匹配版本的 cargo-pgx。

许可证

Portions Copyright 2019-2021 ZomboDB, LLC.  
Portions Copyright 2021-2022 Technology Concepts & Design, Inc. <support@tcdi.com>. 
All rights reserved.
Use of this source code is governed by the MIT license that can be found in the LICENSE file.