pgcentralfoundation/pgrx v0.8.0

on GitHub

Welcome to pgrx v0.8.0 (formally known as pgx). This release of pgrx comes with a number of bugfixes, features, and breaking API changes.

Upgrading

When upgrading, you'll likely want to remove the old "pgx" from your system:

cargo pgx stop all                # from inside an extension crate still using pgx
cargo uninstall cargo-pgx
cargo install cargo-pgrx --locked
cargo pgrx init

This will remove the old cargo-pgx binary, install the new cargo-pgrx binary, and initialize it. This means your development databases will be re-created in, by default, ~/.pgrx.

What's Changed

Breaking Changes

We Have a New Name

We're working on some exciting near-term plans for pgrx and in order to accomplish these goals it was necessary to rename the project. The last thing we want is direct confusion with other open-source projects and corporations also operating in the PostgreSQL space.

• Rename to pgrx by @eeeebbbbrrrr in #1107
• PgXactCallbackEvent shouldn't have been renamed! by @eeeebbbbrrrr in #1108
• Fix broken links to zombodb/pgrx by @syvb in #1109
• Fix pgrx@crates.io link in CONTRIBUTING.md by @workingjubilee in #1110

UTF8 Support

Postgres supports numerous database encodings. Rust only supports UTF8, which here in 2023 is generally what everyone uses in Postgres anyways. These commits cause pgrx to raise ERRORs in cases when it tries to convert a Postgres "string" into a Rust string and it's not valid UTF8. Previously, pgrx blindly did this conversion which could have led to undefined behavior. The detection is minimal-to-no overhead in the case where the database is UTF8 -- it's non-UTF8 encodings where we have to validate compatibility string-by-string.

• Enforce UTF-8 correctness by @workingjubilee in #1094
• Memoize DB encoding for faster validation by @workingjubilee in #1095

Arrays

The pgrx Array type has been drastically overhauled to be properly safe and nearly zero-copy. This means that pgrx is now capable of directly decoding the binary Postgres array format without asking Postgres to deconstruct it into an array of Datums. In the common cases of pass-by-value Datums (ie, i32, f32), Array is truly zero-copy. For arrays of "varlena" types like String, Datum conversions still occur, but the general overhead is drastically reduced.

The various Array iterators take advantage of this as well.

• Use zero-copy Arrays in --release by @workingjubilee in #1116
• Fixup iterator impls for Array by @workingjubilee in #1115
• Carry less usizes in Array by @workingjubilee in #1120
• Make Array::as_slice unsafe by @thomcc in #1083
• Remove Array::as_slice by @workingjubilee in #1119

direct_function_call

The direct_function_call() method now takes a slice for its argument Option<Datum> array instead of a Vec<Option<Datum>>. This will avoid a heap allocation for every usage of this function, making it a little more lightweight.

• Use a slice instead of a vec in direct_function_call and related functions by @thomcc in #1084

New Things

cargo-pgrx

In their first contribution, @azam taught the various cargo-pgrx commands to understand the lib.name property from the extension's Cargo.toml. If present, this will be used to name the resulting shared library. There's an example for this in ./pgrx-examples/custom_libname, but we're talking about, in Cargo.toml:

[lib]
crate-type = ["cdylib"]
name = "other_name"	# you can rename the extension with this

• Support for library with different name than crate name by @azam in #1100

And @yrashk, in yet-another-great-contribution, has given cargo-pgrx an info command. cargo pgrx info has a number of subcommands to report various information about the cargo-pgrx runtime like Postgres installation paths, pg_config paths, and version information.

• Add cargo pgrx info command family by @yrashk in #1092

Spi

pgrx's Spi implementation will automatically/transparently use read_only = false statements when it detects the current transaction has previously been modified. We used to handle this via a pair of transaction callback hooks, and its understanding of "has the current transaction been modified" was limited to what might have happened only in the pgrx extension. We now better detect this, regardless of what modified the transaction, and also do it without transaction callback hooks.

• No xact callback for spi mutability by @eeeebbbbrrrr in #1104

#[pg_extern]

#[pg_extern] now supports security_invoker and security_definer properties. If neither is specified, security_invoker is the default, as per the CREATE FUNCTION specification.

• Add support for explicitly specifying SECURITY INVOKER/DEFINER functions by @JohnHVancouver in #1097

impl Sum/Default for AnyNumeric

The AnyNumeric type is now able to be used by the std::iter::Sum trait to, for example, sum the values of an iterator of AnyNumerics, perhaps coming from Array<AnyNumeric>.

• impl Sum and Default for AnyNumeric by @eeeebbbbrrrr in #1117

More Headers

catalog/objectaccess.h, commands/user.h, optimizer/plancat.h, plpgsql.h, and rewrite/rowsecurity.h are now included as part of the pgrx Rust bindings.

• pgrx-pg-sys: include more headers with hooks by @skyzh in #1077

QoL Improvements

• Allow clippy::no_mangle_with_rust_abi in the entity graph by @thomcc in #1080
• Bump openssl/openssl-sys by @thomcc in #1089
• Avoid some slow HashMap usage where possible by @thomcc in #1075
• An example of how to create a custom type from scratch. by @eeeebbbbrrrr in #1113
• Cleanup build.rs and friends issue #1111 by @eeeebbbbrrrr in #1112

Misc Changes

• Discuss multithreading ergonomics by @workingjubilee in #1081
• Add links to recently published posts on tcdioss.tcdi.com by @rustprooflabs in #1088

New Contributors

• @JohnHVancouver made their first contribution in #1097
• @azam made their first contribution in #1100

Full Changelog: v0.7.4...v0.8.0