repository·develop·Indexed 26 days ago
https://github.com/pgcentralfoundation/pgrxA framework and Cargo subcommand (cargo-pgrx v0.19.1) for developing PostgreSQL extensions in Rust. It provides tools for project scaffolding, managing local Postgres instances, schema generation, and running in-process benchmarks and tests using #[pg_test] and #[pg_bench].
pgrx-sql-entity-graph is a crate designed for SQL Entity Graph generation within the pgrx ecosystem. It is primarily used as an internal dependency by various other pgrx crates to facilitate graph-based representations of SQL entities.The memory_contexts package provides runnable examples demonstrating the PgMemoryContext lifecycle and how memory contexts interact with Set Returning Functions (SRFs) and background workers (bgworkers).
Key examples include:
basics.rs: Demonstrates creating child PgMemoryContexts, using switch_to for scoped allocation, and using reset to reclaim memory. It also covers anti-patterns like use-after-reset.srf_per_call.rs: Compares two SRFs (a streaming SetOfIterator and a materialized TableIterator) and explains the differences between multi_call_memory_ctx and per_query_ctx.bgworker_state.rs: Shows a background worker that allocates long-lived state under TopMemoryContext.CREATE FUNCTION, CREATE TYPE). This approach aims to reduce the need for expert-level knowledge of C, SQL, and Postgres internals by providing safe abstractions.Postgres manages memory using "memory contexts" to prevent leaks. Most extension code runs in transient contexts that are automatically freed at the end of a transaction.
Because the lifetime of an allocation is tied to its memory context, any Rust code returning an allocation must use appropriate lifetime parameters to prevent usage beyond the context's deallocation. In pgrx, the MemCx<'mcx> type is used to represent this relationship, binding the lifetime of the data to the lifetime of the memory context 'mcx.
The pgrx-examples directory provides practical implementations for various pgrx features. Use these examples to learn how to implement specific Postgres extension patterns in Rust, including:
arrays, bytea (as Vec<u8> or &[u8]), strings (text/varlena as String/&str), and composite_type (custom types backed by Rust structs/enums).bgworker), creating custom Operators and Operator Classes, and managing Postgres Shared Memory (shmem).memory_contexts (lifecycle and SRF/bgworker patterns) and error handling (Postgres errors vs. Rust errors/panics).#[pg_bench] examples via cargo pgrx bench.pgrx-pg-sys provides bindgen-generated bindings for pgrx. It is a low-level crate intended to facilitate the interface between Rust and PostgreSQL internals.
Note: This crate is not meant to be used on its own. Developers should use the high-level pgrx crate for extension development.
pgrx-pg-config crate provides an abstraction and wrapper over the standard Postgres pg_config utility. It is designed to be used as a dependency within pgrx projects to programmatically access Postgres configuration and installation details.The pgrx-macros crate provides essential procedural macros and derive macros used to interface Rust code with PostgreSQL. If you are using pgrx as a dependency, you must also include pgrx-macros in your dependency list to enable these features.
Available macros and derives include:
#[pg_extern]: To expose Rust functions to PostgreSQL.#[pg_guard]: For safety/guarding logic.#[pg_guc_hook]: For hooking into Grand Unified Configuration (GUC) settings.#[pg_test]: For testing extension logic.#[derive(PostgresType)]: To map Rust types to PostgreSQL types.#[derive(PostgresEnum)]: To map Rust enums to PostgreSQL enums.#[derive(PostgresGucEnum)]: To map Rust enums to PostgreSQL GUC enums.A PostgreSQL aggregate is defined using CREATE AGGREGATE and typically relies on one or more supporting functions. The core components include:
null).STYPE.Aggregates can also accept multiple arguments, which are passed together for each row processed.
pgrx manages the incompatible error handling models between Postgres (C) and Rust.
sigsetjmp/siglongjmp to jump across stack frames to rollback transactions. This can bypass Rust's Drop implementations, causing memory leaks.sigsetjmp checkpoints, and aborting shuts down the entire database.pgrx uses the #[pg_guard] macro to bridge these two worlds in two different directions: protecting Rust from Postgres ERRORs and protecting Postgres from Rust panic!s.
arrays package provides practical examples of how to handle PostgreSQL array types within a Rust extension using pgrx. This is useful for developers needing to map Postgres array data to Rust collections and perform array-based operations.Because pgrx operates within the Postgres environment, developers must be aware that Rust's Drop::drop implementations are not guaranteed to run. This is because Postgres can interrupt control flow in ways that prevent destructors from starting or finishing.
To maintain safety, pgrx ensures that Rust control flow is independent of Postgres control flow. This is particularly relevant when dealing with non-trivial destructors, as the use of sigsetjmp and siglongjmp (used by pgrx to manage Postgres's machinations) can interact with Rust's execution model.