Skip to content
Search

Pgrx

lastmod 2024-11-20created 2024-11-202 edits

A framework for developing PostgreSQL extensions in Rust

Seems to have been renamed from the former pgx?

Features

  • Develop PostgreSQL extensions in Rust, striving to be as idiomatic & safe as possible
  • Fully managed development environment with cargo-pgrx
    • cargo pgrx new: create a new extension
    • cargo pgrx init: register and manage PostgreSQL installations
    • cargo pgrx run: run and test the extension
    • cargo pgrx test: test against multiple PostgreSQL versions
    • cargo pgrx package: create an extension installation package
  • Multiple PostgreSQL version support
    • Supports PostgreSQL 12 through 17
    • Version-specific APIs can be used selectively via Rust feature gating
    • Integration testing possible for all versions
  • Automatic schema generation
    • Extensions can be implemented in Rust alone
    • Automatically maps many Rust types for PostgreSQL
    • SQL schemas generated automatically or manually with cargo pgrx schema
    • Custom SQL can be included via the extension_sql! and extension_sql_file! macros
  • Safety first
    • Rust's panic! is translated into a PostgreSQL ERROR, aborting only the transaction, not the process
    • Rust memory management model preserved - even across panic! and elog(ERROR)
    • #[pg_guard] macro supports reliable integration between Rust and PostgreSQL
    • Postgres Datums are Option<T> where T: FromDatum
    • NULL Datums are safely represented as Option::<T>::None
  • First-class UDF support
    • Rust functions (Postgres user-defined functions) can be exposed to PostgreSQL with the #[pg_extern] annotation
    • Create trigger functions with #[pg_trigger]
  • User-defined type support
    • Use Rust structs as PostgreSQL types with #[derive(PostgresType)]:
      • Encoded as CBOR in memory/on disk, and represented as JSON in human-readable form
      • Custom memory/disk/JSON representations can be defined
      • Use Rust enums as PostgreSQL enums with #[derive(PostgresEnum)]:
      • Composite types supported via the pgrx::composite_type!("Sample") macro
  • Server Programming Interface (SPI)
    • Safe access to SPI
    • Owned Datums can be returned transparently from the SPI context
  • Advanced features
    • Safe access to Postgres's MemoryContext system via pgrx::PgMemoryContexts
    • Executor/planner/transaction/subtransaction hooks
    • PostgreSQL internals accessible through pgrx::pg_sys using Rust's unsafe
  • Limitations and known issues
    • No multithreading support: Postgres is fundamentally single-threaded, and threads accessing Postgres functions may crash
    • Incomplete async support: interaction with Postgres in an async context is under-researched
    • Lacking Windows support: currently does not fully work on Windows
    • UTF-8 encoding required: errors may occur if the Postgres database is not UTF-8 compatible

See also

Favorite site

author Zer0 sitemap