Crate pgrx

Expand description

pgrx is a framework for creating Postgres extensions in 100% Rust

§Example

use pgrx::prelude::*;

// Convert the input string to lowercase and return
#[pg_extern]
fn my_to_lowercase(input: &str) -> String {
    input.to_lowercase()
}

Re-exports§

pub use datum::AnyArray;
pub use datum::AnyElement;
pub use datum::AnyNumeric;
pub use datum::Array;
pub use datum::FromDatum;
pub use datum::Inet;
pub use datum::Internal;
pub use datum::IntoDatum;
pub use datum::Json;
pub use datum::JsonB;
pub use datum::Numeric;
pub use datum::Range;
pub use datum::Uuid;
pub use datum::VariadicArray;
pub use datum::geo;
pub use datum::numeric;
pub use spi::Spi;
pub use pgrx_macros;
pub use aggregate::*;
pub use atomics::*;
pub use callbacks::*;
pub use enum_helper::*;
pub use fcinfo::*;
pub use guc::*;
pub use htup::*;
pub use inoutfuncs::*;
pub use list::old_list::*;
pub use lwlock::*;
pub use memcxt::*;
pub use namespace::*;
pub use nodes::*;
pub use pgbox::*;
pub use rel::*;
pub use shmem::*;
pub use stringinfo::*;
pub use trigger_support::*;
pub use tupdesc::*;
pub use varlena::*;
pub use wrappers::*;
pub use xid::*;

Modules§

aggregate: Aggregate support.
array
atomics
bgworkers: Safely create Postgres Background Workers, including with full SPI support
callbacks: Provides safe wrappers around Postgres’ “Transaction” and “Sub Transaction” hook system
callconv: Helper implementations for returning sets and tables from #[pg_extern]-style functions
datetime
datum: Handing for easily converting Postgres Datum types into their corresponding Rust types and converting Rust types into their corresponding Postgres types
enum_helper: Helper functions for working with Postgres enum types
fcinfo: Helper functions for creating Postgres UDFs
ffi: Reexport FFI definitions here.
fn_call
guc: Provides a safe interface into Postgres’ Configuration System (GUC)
heap_tuple: Provides a safe interface to Postgres HeapTuple objects.
htup: Utility functions for working with pg_sys::HeapTuple and pg_sys::HeapTupleHeader structs
inoutfuncs: Helper trait for the #[derive(PostgresType)] proc macro for overriding custom Postgres type input/output functions.
itemptr: Helper functions for working with Postgres ItemPointerData (tid) type
iter
layout: Code for interfacing with the layout in memory (and on disk?) of various data types within Postgres. This is not a mature module yet so prefer to avoid exposing the contents to public callers of pgrx, as this is error-prone stuff to tamper with. It is easy to corrupt the database if an error is made. Yes, even though its main block of code duplicates htup::DatumWithTypeInfo.
list: A safe wrapper around Postgres’ internal List structure.
lwlock
memcx: Memory Contexts in PostgreSQL, now with lifetimes.
memcxt: Provides interfacing into Postgres’ MemoryContext system.
misc
namespace: A helper struct for creating a Postgres List of Strings to qualify an object name
nodes: Helper functions and such for Postgres’ various query tree Nodes
nullable: Traits and implementations of functionality relating to Postgres null and nullable types, particularly in relation to arrays and other container types which implement nullable (empty slot) behavior in a “structure-of-arrays” manner
palloc
pg_catalog
pg_sys: dirty hacks
pgbox
prelude: The PGRX prelude includes necessary imports to make extensions work.
rel: Provides a safe wrapper around Postgres’ pg_sys::RelationData struct
shmem
spi: Safe access to Postgres’ Server Programming Interface (SPI).
spinlock
stringinfo: A safe wrapper around Postgres StringInfo structure
trigger_support: Support for writing Rust trigger functions
tupdesc: Provides a safe wrapper around Postgres’ pg_sys::TupleDescData struct
varlena: Helper functions to work with Postgres varlena * structures
wrappers: Provides safe wrapper functions around some of Postgres’ useful functions.
xid

Macros§

FATAL: Log to Postgres’ fatal log level. This will abort the current Postgres backend connection process.
PANIC: Log to Postgres’ panic log level. This will cause the entire Postgres cluster to crash.
check_for_interrupts: If an interrupt is pending (perhaps a user-initiated “cancel query” message to this backend), this will safely abort the current transaction
composite_type: Composite type support
debug1: Log to Postgres’ debug1 log level.
debug2: Log to Postgres’ debug2 log level.
debug3: Log to Postgres’ debug3 log level.
debug4: Log to Postgres’ debug4 log level.
debug5: Log to Postgres’ debug5 log level.
default: A macro for specifying default argument values so they get properly translated to SQL in CREATE FUNCTION statements
ereport: Sends some kind of message to Postgres, and if it’s a PgLogLevel::ERROR or greater, Postgres’ error handling takes over and, in the case of PgLogLevel::ERROR, aborts the current transaction.
ereport_domain: Send some kind of message to Postgres similar to the ereport macro, while specifying a text domain, analogous to Postgres’ ereport_domain C macro.
error: Log to Postgres’ error log level. This will abort the current Postgres transaction.
extension_sql: Declare SQL to be included in generated extension script.
extension_sql_file: Declare SQL (from a file) to be included in generated extension script.
function_name: This macro returns the name of the enclosing function. As the internal implementation is based on the std::any::type_name, this macro derives all the limitations of this function.
impl_sql_translatable: Implements SqlTranslatable for a type with a fixed external SQL mapping.
info: Log to Postgres’ info log level.
log: Log to Postgres’ log log level.
name: A macro for providing SQL names for the returned fields for functions that return a Rust tuple, especially those that return a TableIterator.
notice: Log to Postgres’ notice log level.
oids_of: Creates an array of pg_sys::Oid with the OID of each provided type
pg_magic_func: Create the Pg_magic_func required by PGRX in extensions.
pg_module_magic: A macro for marking a library compatible with pgrx.
pg_shmem_init: In order to store a type in Postgres Shared Memory, it must be passed to pg_shmem_init!() during _PG_init().
pgrx_resolved_type
warning: Log to Postgres’ warning log level.

Structs§

PgTryBuilder: PgTryBuilder is a mechanism to mimic Postgres C macros PG_TRY and PG_CATCH.

Enums§

PgLogLevel: Postgres’ various logging levels
PgOid
PgSqlErrorCode: This list of SQL Error Codes is taken directly from Postgres 12’s generated “utils/errcodes.h”

Constants§

FATAL
PANIC

Functions§

name_data_to_str: Converts a pg_sys::NameData struct into a &str.

Type Aliases§

PgBuiltInOids

Attribute Macros§

commutator: Used with #[pg_operator]. 1 value which is the function name
hashes: Used with #[pg_operator]. no values
initialize: Associated macro for #[pg_test] to provide context back to your test framework to indicate that the test system is being initialized
join: Used with #[pg_operator]. 1 value which is the function name
merges: Used with #[pg_operator]. no values
negator: Used with #[pg_operator]. 1 value which is the function name
opname: Used with #[pg_operator]. 1 value which is the operator name itself
pg_aggregate: Declare a pgrx::Aggregate implementation on a type as able to used by Postgres as an aggregate.
pg_bench: #[pg_bench] functions are in-process Criterion-driven benchmarks that run inside Postgres during cargo pgrx bench.
pg_cast: Declare a function as #[pg_cast] to indicate that it represents a Postgres cast.
pg_extern: Declare a function as #[pg_extern] to indicate that it can be used by Postgres as a UDF.
pg_guard: Declare a function as #[pg_guard] to indicate that it is called from a Postgres extern "C-unwind" function so that Rust panic!()s (and Postgres elog(ERROR)s) will be properly handled by pgrx
pg_guc_hook: Declare a function as a GUC hook. This takes one argument: show, check, or assign.
pg_operator: Declare a function as #[pg_operator] to indicate that it represents a Postgres operator cargo pgrx schema will automatically generate the underlying SQL
pg_schema: Declare a Rust module and its contents to be in a schema.
pg_test: #[pg_test] functions are test functions (akin to #[test]), but they run in-process inside Postgres during cargo pgrx test.
pg_trigger: Create a PostgreSQL trigger function
pgrx: A helper attribute for various contexts.
restrict: Used with #[pg_operator]. 1 value which is the function name
search_path: Associated macro for #[pg_extern] or #[macro@pg_operator]. Used to set the SEARCH_PATH option on the CREATE FUNCTION statement.

Derive Macros§

AggregateName: Derives the ToAggregateName trait.
PostgresEnum: Generate necessary bindings for using the enum with PostgreSQL.
PostgresEq: Generate necessary code using the type in operators like == and !=.
PostgresGucEnum: Derives the GucEnum trait, so that normal Rust enums can be used as a GUC.
PostgresHash: Generate necessary code for stable hashing the type so it can be used with USING hash indexes.
PostgresOrd: Generate necessary code using the type in operators like >, <, <=, and >=.
PostgresType: Generate necessary bindings for using the type with PostgreSQL.

Crate pgrx

Crate pgrx Copy item path

§Example

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Functions§

Type Aliases§

Attribute Macros§

Derive Macros§

Crate pgrx