Crate pgrx

Source
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§

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.
  • hooksDeprecated
    A trait and registration system for hooking Postgres internal operations such as its planner and executor
  • 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.
  • 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§

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§

Functions§

Type Aliases§

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" 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§

  • 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.