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::numeric;
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 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
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
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.
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.
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_embed: Entry point for cargo-pgrx’s schema generation so that PGRX’s framework can generate SQL for its types and functions and topographically sort them into an order Postgres will accept. Typically written by the cargo pgrx new template, so you probably don’t need to worry about this.
variadicDeprecated
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_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_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