github pgcentralfoundation/pgrx v0.7.0-beta.0
on GitHub

latest releases: v0.12.5, v0.12.4, v0.12.3...
20 months ago

This is pgx v0.7.0-beta.0. Other than pgx' initial release, this is our biggest release yet! It contains a number of safety improvements, segfault fixes, API changes, minor performance improvements, and an overhauled Spi interface now with prepared statements and cursors!

Quite a number of people have contributed to this release, so a big thank you is necessary right here at the top. Some notable names are @yrashk and @EdMcBane for their work on Spi. And a shout-out to the new contributors: @jaskij, @kianmeng, and @ChuckHend.

To use this beta release, install cargo-pgx by version: $ cargo install cargo-pgx --version 0.7.0-beta.0 --locked and make sure to update your extension crate dependencies to use 0.7.0-beta.0 too.

API Changes

v0.7.0 contains some backwards incompatible API changes and your extension code may need to be updated as a result. Leaning on the compiler should help you through the changes.

Spi

Spi has received a major overhaul in v0.7.0. It now supports cursors, prepared statements, and runtime datum conversion error detection.

Much of the Spi API has been overhauled in a backwards-incompatible way, and is too much to document in release notes. However, the biggest change is that the various getter functions on Spi and SpiTupleTable and SpiHeapTupleData now return pgx::spi::Result<Option<T>>. The error type is pgx::spi::Error and can not only report Postgres-specific SPI_ERROR_XXX errors from Postgres but also represent runtime situations where the requested Rust type T isn't compatible with the backing Datum type.

Cursor Support Changes

Prepared Statement Support

  • Prepared statements and Query trait by @yrashk in #885

Spi Statement "readonly" Management

Spi Error Handling

Because most Spi-related functions now return spi::Result<T>, pgx now knows how to convert a Result<T: IntoDatum, E: Any + Display> into a Datum. This means #[pg_extern]-style functions (including #[pg_test] functions) can now return a Result. This makes working with Spi much more "rust-like" and fluent.

If result is Ok then its payload is converted into a Datum. If the result is Err, then pgx will automatically raise a Postgres ERROR. Furthermore, if the Err variant's payload is a pgx ErrorReport, then that'll be raised, which can include a specific SQL error code, detail, hint, and context message.

The general work on Spi error handling happened in these PRs, with much help from @yrashk and @EdMcBane:

And the generalized support for handling Results-as-Datums came in through:

General Cleanups

This one is particularly interesting as it now allows cargo test --all --features "pgXX ... ..." to work from a top-level workspace crate:

  • Teach pgx-tests/src/framework.rs to detect cargo test feature arguments by @eeeebbbbrrrr in #967

Stability, Correctness, and Performance

  • Problem: can't use pg_guard on parameterized functions by @yrashk in #918
  • Handle panics in PgMemoryContexts::switch_to by @yrashk in #920
  • Ensure setting owned memory context as current twice won't lead to problems (bugfix) by @yrashk in #956
  • Improve error handling during code generation by converting some panics into syn::Errors by @thomcc in #919
  • Set returning #[pg_extern] functions can cause segfault by @eeeebbbbrrrr in #982
  • PgLwLock: skip releasing the lock when unwinding from an elog call in postgres code by @EdMcBane in #989
  • :enh: bail out early in do_ereport if errstart returns false by @EdMcBane in #980
  • Rewrite StringInfo by @eeeebbbbrrrr in #903
  • Optimize our String/&str/Vec/&[u8] IntoDatum conversions by @eeeebbbbrrrr in #952

Feature Flags

When enabled, pgx will not generate any code related to the "sql entity graph", thereby causing cargo-pgx to generate an empty schema.

When enabled (which is the default), pgx (specifically, pgx-pg-sys) will compile its "cshim" code and have it statically linked into the extension. Disabling this feature flag might make pgx compilation easier for platforms where the necessary Postgres C extension build requirements aren't available, however you'll lose access to a few pgx modules: hooks, list, namespace and spinlock.

Our ultimate goal is to not have a "cshim" at all, and to that end much of the old "cshim" has been ported to Rust:

  • Port c-shim.c heap_getattr, HeapTupleHeaderGetXmin, and HeapTupleHeaderGetRawCommandId to Rust by @eeeebbbbrrrr in #953
  • Port c-shim.c pgx_GETSTRUCT and pgx_HeapTupleHeaderGetOid to Rust by @eeeebbbbrrrr in #950
  • Port various c-shim.c SET_VARSIZE* functions to Rust by @eeeebbbbrrrr in #949
  • PgMemoryContexts::get_context_for_pointer() is wildly unsafe. by @eeeebbbbrrrr in #947
  • Port c-shim.c's pgx_ereport() function to rust by @eeeebbbbrrrr in #946
  • Port various c-shim.c ARR_* functions to Rust by @eeeebbbbrrrr in #948

More Postgres Headers

CI Updates

New Contributors

A Note From @eeeebbbbrrrr

To all the pgx users and most especially the contributors that had PRs open for awhile, and then has those PRs merged to just sit there even longer, thank you for being patient. I, and the core pgx team, recognize that was a thing.

I personally wanted v0.7.0 to collect as many breaking changes as we could, especially around Spi, in the hopes that future releases will have far fewer breaking changes. I also wanted the Spi overhaul to be worth the wait, and I really believe it is!

I can't promise that future releases will have less breaking changes, but that is a goal.

Full Changelog: v0.6.1...v0.7.0-beta.0

Check out latest releases or
releases around pgcentralfoundation/pgrx v0.7.0-beta.0

Don't miss a new pgrx release

NewReleases is sending notifications on new releases.

Get notifications