pgcentralfoundation/pgrx
Pgrx
pgrx is a framework for building and packaging custom PostgreSQL extensions using Rust. It serves as a foreign function interface bridge that maps Rust types and functions to the internal server programming interface of the database.
The project provides a specialized toolchain for cross-compilation across different operating systems and target architectures using custom sysroots. It includes a schema generator that automatically translates high-level language structures into SQL definitions and binary protocol mappings.
The framework manages memory safety by wrapping database memory contexts and translating runtime panics into database-level errors to prevent server crashes. It further supports the definition of custom native database types and the implementation of functions and triggers.
A command line interface is provided to manage the extension lifecycle, including building, testing, and packaging across multiple database versions.
Features
- Rust Extension Frameworks - Provides a framework for building and packaging custom PostgreSQL extensions entirely in Rust.
- Rust Frameworks - Serves as the primary Rust framework for building and packaging custom PostgreSQL extensions with memory safety.
- PostgreSQL Custom Type Derivation - Derives PostgreSQL types, enums, and composites directly from Rust structs and enums with automatic serialization.
- PostgreSQL - Derives PostgreSQL types from Rust structs and enums with automatic binary protocol support.
- Server Programming Interfaces - Executes SQL queries safely from within extensions using a managed Server Programming Interface.
- Build Toolchains - Provides a complete cargo-based toolchain for cross-compiling, testing, and packaging PostgreSQL extensions.
- Custom Type Derivation - Derives PostgreSQL types from Rust structs and enums with automatic serialization and binary protocol support.
- Custom Type Implementations - Creates native PostgreSQL data types from Rust structs and enums with automatic serialization and binary protocol support.
- Safe Internal Access - Provides safe wrappers for PostgreSQL memory contexts and internals with panic-to-error safety guarantees.
- Safe Internal Access Wrappers - Provides safe wrappers for PostgreSQL memory contexts and pointers with panic-to-error translation.
- Rust - Converts between PostgreSQL and Rust types automatically, including zero-copy for text and bytea.
- User-Defined Functions - Exposes Rust functions as PostgreSQL user-defined functions via declarative attribute macros.
- Rust User-Defined Functions - Annotates Rust functions to register them as PostgreSQL user-defined functions and triggers.
- PostgreSQL UDF Development Toolkits - Provides a complete toolkit for defining PostgreSQL user-defined functions, triggers, and custom types in Rust.
- PostgreSQL User-Defined Functions - Defines user-defined functions and triggers in PostgreSQL using Rust code with automatic SQL schema generation.
- Extension Development Environments - Provides a cargo subcommand to scaffold, test, and package extensions across multiple PostgreSQL versions.
- SQL Schema Generators - Automatically derives SQL type definitions and binary protocol mappings from Rust structs and enums.
- Database Memory Context Wrappers - Wraps PostgreSQL memory contexts in Rust's ownership model for automatic allocation management.
- PostgreSQL Memory Context Wrappers - Wraps PostgreSQL memory contexts in Rust's ownership model and converts panics to database-level errors.
- PostgreSQL FFI Bridges - Maps Rust types and functions to PostgreSQL's internal server programming interface through a foreign function bridge.
- Attribute-Macro Code Generators - Translates annotated Rust functions into PostgreSQL-compatible C entry points using procedural macros.
- PostgreSQL Internal Safe Wrappers - Provides safe wrappers for PostgreSQL pointers and memory contexts, with optional direct unsafe access to internals.
- PostgreSQL Memory Context Safety - Handles PostgreSQL memory contexts with Rust's drop semantics, preventing leaks even during panics or errors.
- Cross-Language Panic Mapping - Converts Rust panics into PostgreSQL errors that abort only the current transaction.
- Server Programming Interfaces - Provides safe Rust bindings to PostgreSQL's Server Programming Interface for executing queries within extensions.
- Panic Recovery - Translates Rust panics into PostgreSQL errors that abort the transaction without crashing the server process.
- Database - Translates Rust panics into PostgreSQL errors that abort only the current transaction, preventing server crashes.
- Extension Cross-Compilation - Compiles and packages PostgreSQL extensions for multiple operating systems and database versions.
- Sysroot Toolchains - Provides custom sysroots and build scripts to compile Rust extensions for multiple platforms.
- Zero-Copy Mappings - Maps PostgreSQL text and bytea types to Rust slices without copying data using pointer aliasing.
- Extension Testing Environments - Launches a PostgreSQL instance with the extension loaded and opens an interactive psql session.
- Extension Scaffolders - Generates a new PostgreSQL extension project with a single command providing a ready-to-use structure.
- Extension Packaging Tools - Creates installation packages for the extension ready for deployment to other systems.
- Version Target Controls - Supports building and testing extensions against PostgreSQL versions 13 through 18 from a single codebase.
- Database Version Compatibility - Runs extension unit tests against multiple installed PostgreSQL versions from a single command.
- Cross-Version Testing - Runs extension unit tests against multiple installed PostgreSQL versions from a single command.
- Database Version Compatibility - Runs unit tests against multiple installed PostgreSQL versions to ensure cross-version compatibility.
- SQL Schema Generators - Produces SQL schema files automatically from Rust extension code or custom SQL includes.
