Pgrx: Build Postgres Extensions with Rust

Build Postgres Extensions with Rust!

pgrx is a framework for developing PostgreSQL extensions in Rust and strives to be as idiomatic and safe as possible.

pgrx supports Postgres 13 through Postgres 18.

A fully managed development environment with cargo-pgrx

• cargo pgrx new: Create new extensions quickly
• cargo pgrx init: Install new (or register existing) PostgreSQL installs
• cargo pgrx run: Run your extension and interactively test it in psql (or pgcli)
• cargo pgrx test: Unit-test your extension across multiple PostgreSQL versions
• cargo pgrx package: Create installation packages for your extension

Target Multiple Postgres Versions

• Support from Postgres 13 to Postgres 17 from the same codebase
• Use Rust feature gating to use version-specific APIs
• Seamlessly test against all versions

Automatic Schema Generation

• Implement extensions entirely in Rust
• Automatic mapping for many Rust types into PostgreSQL
• SQL schemas generated automatically (or manually via cargo pgrx schema)
• Include custom SQL with extension_sql! & extension_sql_file!

Safety First

• Translates Rust panic!s into Postgres ERRORs that abort the transaction, not the process
• Memory Management follows Rust's drop semantics, even in the face of panic! and elog(ERROR)
• #[pg_guard] procedural macro to ensure the above
• Postgres Datums are Option<T> where T: FromDatum. NULL Datums are safely represented as Option::<T>::None

First-class UDF support

• Annotate functions with #[pg_extern] to expose them to Postgres
• Return pgrx::iter::SetOfIterator<'a, T> for RETURNS SETOF
• Return pgrx::iter::TableIterator<'a, T> for RETURNS TABLE (...)
• Create trigger functions with #[pg_trigger]

Easy Custom Types

• #[derive(PostgresType)] to use a Rust struct as a Postgres type
• #[derive(PostgresEnum)] to use a Rust enum as a Postgres enum
• Composite types supported with the pgrx::composite_type!("Sample") macro

Server Programming Interface (SPI)

• Safe access into SPI
• Transparently return owned Datums from an SPI context

Advanced Features

• Safe access to Postgres' MemoryContext system via pgrx::PgMemoryContexts
• Executor/planner/transaction/subtransaction hooks
• Safely use Postgres-provided pointers with pgrx::PgBox<T>
• Access Postgres' logging system through eprintln!-like macros
• Direct unsafe access to large parts of Postgres internals via the pgrx::pg_sys module