$ show pgcentralfoundation/pgrx
This repository provides **pgrx**, a framework for writing PostgreSQL extensions entirely in Rust. It includes a CLI tool (`cargo-pgrx`) for project scaffolding, building, testing, packaging, and schema generation. The core library (`pgrx`) offers safe Rust wrappers for PostgreSQL internals: memory contexts, SPI (Server Programming Interface), arrays, triggers, aggregates, GUCs, datetime types, and more. Procedural macros (`#[pg_extern]`, `#[pg_trigger]`, `#[pg_aggregate]`, `#[derive(PostgresType)]`, etc.) automatically generate SQL DDL and Rust boilerplate, enabling a pure-Rust extension development experience. The framework supports PostgreSQL versions 13 through 19 via feature-gated FFI bindings in `pgrx-pg-sys`, which uses `bindgen` to produce per-version Rust declarations. SQL schema generation is handled at compile time by `pgrx-sql-entity-graph`, which embeds metadata in the shared library's binary sections. The architecture is modular: the `pgrx` crate re-exports public API, `pgrx-macros` provides proc macros, `pgrx-pg-sys` contains raw FFI bindings, `pgrx-sql-entity-graph` handles SQL generation, and `cargo-pgrx` is the CLI frontend. Example extensions in `pgrx-examples/` demonstrate features like custom types, background workers, logical decoding, and SPI usage. A comprehensive test suite in `pgrx-unit-tests/` includes compile-fail tests, property-based tests (via `proptest`), and integration tests that run against real PostgreSQL instances. Key external dependencies include the PostgreSQL development headers (for `pg_config` and C API), `libclang` for bindgen, and Rust ecosystem crates such as `serde`, `syn`, `quote`, `clap`, `ureq`, and `criterion` (for benchmarking). The framework is designed for extension authors; it is not a data analysis or research project.
The LLM identified 3 files worth highlighting for reuse:
Provides `PgMemoryContexts` and `MemCx` types for safe management of PostgreSQL memory contexts. `PgMemoryContexts` is an enum representing all context variants (current, top, memory-switched, etc.) with methods like `switch_to()` and `leak_and_drop_on_delete()`. `MemCx` tracks the current context and automatically switches back on drop. This abstraction encapsulates Postgres's C-level memory management into a Rust-friendly, RAII-based API that prevents memory leaks and use-after-free errors. The design is self-contained (depends only on `pgrx-pg-sys` and standard library) and could be extracted for any Rust extension needing safe Postgres memory handling.
Implements `SpiClient` for safe execution of SQL queries via PostgreSQL's Server Programming Interface. Provides methods for running SQL, executing prepared statements, opening cursors, and extracting typed results. Handles transaction state, error conversion (Postgres errors to Rust `Result`), and memory context management. The abstraction is layered: `Spi::connect()` returns a client that ensures proper cleanup on drop. This module is a reusable pattern for any extension that needs to query the database from within a function, with minimal coupling (only depends on `pgrx::pg_sys` and `pgrx::datum`).
Defines `FlatArray<T>` for iterating over PostgreSQL arrays with efficient null handling and dimension access. Uses a pointer to the raw `ArrayType` struct and provides methods like `iter()` that decode elements lazily, respecting the null bitmap. Supports both scalar types (via `Scalar` trait for copy optimization) and composite types. The implementation handles multi-dimensional arrays, null filtering, and bounds checking. This module demonstrates a zero-copy, memory-safe wrapper around Postgres's variable-length array format. It is self-contained (depends on `pgrx::datum` and `pgrx::pg_sys`) and could be reused for any project needing to read Postgres arrays from Rust without copying.