Crate pgx

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

Example

use pgx::prelude::*;

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

Re-exports

• pub use pgx_macros;
• pub use spi::Spi;
• pub use pgx_pg_sys as pg_sys;
• pub use aggregate::*;
• pub use atomics::*;
• pub use callbacks::*;
• pub use datum::*;
• pub use enum_helper::*;
• pub use fcinfo::*;
• pub use guc::*;
• pub use hooks::*;
• pub use htup::*;
• pub use inoutfuncs::*;
• pub use itemptr::*;
• pub use 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
• 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.
• guc
  Provides a safe interface into Postgres’ Configuration System (GUC)
• heap_tuple
  Provides a safe interface to Postgres HeapTuple objects.
• hooks
  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
• list
  A safe wrapper around Postgres’ internal List structure.
• lwlock
• 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
• pgbox
• prelude
  The PGX 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 PGX in extensions.
• pg_module_magic
  A macro for marking a library compatible with pgx.
• pg_shmem_init
  In order to store a type in Postgres Shared Memory, it must be passed to pg_shmem_init!() during _PG_init().
• pg_sql_graph_magic
  Create necessary extension-local internal marker for use with SQL generation.
• variadic
• 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

• initialize
  Initialize the extension with Postgres
• name_data_to_str
  Converts a pg_sys::NameData struct into a &str.

Type Definitions

• 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 pgx::Aggregate implementation on a type as able to used by Postgres as an aggregate.
• 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 pgx
• pg_operator
  Declare a function as #[pg_operator] to indicate that it represents a Postgres operator cargo pgx 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 pgx test.
• pg_trigger
  Create a PostgreSQL trigger function
• pgx
  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.