Skip to content

Releases: pgcentralfoundation/pgrx

v0.7.3

09 Mar 16:03
68fe53c
Compare
Choose a tag to compare

Welcome to pgx v0.7.3. It has a few minor bugfixes and API additions, along with an API-breaking change related to GUCs.

When upgrading please install cargo-pgx with cargo install cargo-pgx --locked.

What's New

New functions (pgx::spi::{quote_identifier, quote_qualified_identifier, quote_literal}) have been added to quote SQL identifiers and literals. These all delegate back into Postgres, so Postgres' quoting rules apply.

This adds a new pgx::gucs::GucFlags struct along with a new flags: GucFlags argument to the various GucRegistry::define_xxx_guc() functions. This is a user-facing API change, but it allows, among other things, for a GUC to indicate that maybe its unit is a byte or seconds. Specifying GucFlags::default() as this argument will quickly migrate your code while maintaining backwards compatibility.

Now, when running a cargo pgx init where pgx compiles Postgres, it'll include all the contrib/ packages as well. This will let you also use extensions like hstore or citext in the databases managed by cargo-pgx.

If you'd like to do this now, just run cargo pgx init again. Your existing databases will be preserved.

Bug Fixes

The IntoDatum implementation for these types made an awful assumption that the backing pointer was already palloc'd by Postgres. This is not what CString and CStr mean, and this assumption could have led to UAF. They've been re-implemented to copy the backing pointer to a palloc'd memory.

If you are wanting to convert a raw, palloc'd pointer into a Datum, just use Datum::from(ptr).

The cargo-pgx CLI tool can use a proxy when it makes network requests. This generalizes the proxy url parsing such that "https" is not hardcoded and is instead intuited from the proxy string itself.

Other Changes

  • Bump tempfile dep to 3.4.0, and several other deps. by @thomcc in #1059

New Contributors

Full Changelog: v0.7.2...v0.7.3

v0.7.2

23 Feb 20:21
809132b
Compare
Choose a tag to compare

This is pgx v0.7.2. It contains quite a few bugfixes and API changes (some of which are breaking).

When updating please make sure to update your crate dependencies and also:

$ cargo install cargo-pgx --version 0.7.2 --locked

API Changes

There's quite a bit of changes to trigger support. PgTrigger is now parameterized with a lifetime and #[pg_trigger] functions will need to adapt to this. Additionally, #[pg_trigger] functions must now return an Option<PgHeapTuple>> (or Result<Option<PgHeapTuple>, E>) as previously it wasn't possible to return a NULL tuple (ie, Option::None), indicating that the row being acted upon should not be modified.

Range support has been changed quite a bit to be more ergonomic and provide conversion from Rust std::ops::Range* types. Check out the new example in pgx-examples/range/.

  • a better Error type when conversion from Date to time::Date doesn't work by @eeeebbbbrrrr in #1052

This is only relevant when the pgx/time-crate feature is used

Correctness Issues

  • By default, require superuser privileges to install a pgx extension by @vadim2404 in #1056

This only impacts new extension crates made with cargo pgx new. It's better that pgx assume the extension you're about to make is wildly unsafe and for you to change that assumption in its extname.control file if you disagree.

  • Fix the IntoDatum implementations for both pg_sys::Point and pg_sys::BOX by @eeeebbbbrrrr in #1042

  • Extend UTF-8 detection in PGX init and test by @sumerman in #1041

Bug Fixes

pgx extensions can now be built against Postgres forks, but you'll need to turn on the pgx/unsafe-postgres feature for your pgx dependency.

  • Use SPITupleTable->numvals when available by @yrashk in #1037

  • Support in FromDatum for binary coercible types (including domain types) by @EdMcBane in #1028

This allows slightly more automatic conversions between data types for Spi. Especially when the Postgres type is a DOMAIN over something like TEXT and the desired Rust type is a String

pgx no longer knows that it's being used with postgrestd

cargo pgx init no longer assumes a user named "root" exists on the system

Miscellaneous

If you run Postgres or cargo pgx run with RUST_BACKTRACE=1 set in the environment, then whenever pgx catches a panic, it'll include a full backtrace!

  • Ensure the libpq{,N}-dev package is removed in CI by @thomcc in #1034

  • Fix outdated documentation for pgx::name! by @Smittyvb in #1036

  • Disable thin lto for dev builds by default in template by @JelteF in #1035

  • Respect RUSTC/CARGO environment variables, and handle calls through cargo in cargo-pgx and pgx-test by @thomcc in #1038

  • Fix some warnings when the time-crate feature is disabled by @thomcc in #1054

New Contributors

Thanks everyone!

Full Changelog: v0.7.1...0.7.2

v0.7.1

02 Feb 18:56
4b9467a
Compare
Choose a tag to compare

Welcome to pgx v0.7.1. It is a small point release that primarily finishes Numeric support. That said, it wouldn't be a proper pgx release without at least one possible breaking API change.

As always, make sure to install cargo-pgx with cargo install cargo-pgx --version 0.7.1 --locked and update crate dependencies as well.

New Trait Impls

  • Support all the Rust "math" operations (Add, Sub, Mul, Div, Rem) for Numeric<P, S> and AnyNumeric against primitives (and each other) by @eeeebbbbrrrr in #1029

Breaking API Change

Our prior usages of cstr_core were to work around the fact that Rust's CStr/CString types required std. As of Rust v1.64, they can be used in no_std environments (which pgx, surprisingly!, supports), so there is no longer a need for us to rely on cstr_core and to re-export it as our own type.

You may run into compilation issues if you implement custom Aggregates.

Something Interesting

This ought to be considered experimental. If you do need to make a 32bit pgx extension and run into problems, please let us know.

Full Changelog: v0.7.0...v0.7.1

v0.7.0

25 Jan 15:37
b5806e3
Compare
Choose a tag to compare

After two betas with minimal (reported) issues, pgx v0.7.0 is finally here!

The full set of code changes since pgx' previous version series (0.6.x) can be found here. It might also be beneficial to review the release notes for the 0.7.0-betas at beta0 and beta1

Below is the small set of changes since beta1.

As always, please make sure to install the latest cargo-pgx with cargo install cargo-pgx --version 0.7.0 --locked and update your extension crate dependencies.

Thanks to all the contributors and users. pgx wouldn't be possible without your participation!

What's Changed

A New Hook

This allows extensions to intercept "ereport" messages as they're emitted by either Postgres or pgx. Maybe you've always wanted to send log messages to some external collection system? Now you can!

Cross Compilation Support

  • Allow manually choosing the scratch directory in cargo pgx cross pgx-target by @thomcc in #1016
  • Fix confusing typo in CROSS_COMPILE.md about rustup target add vs rustup toolchain add by @thomcc in #1017
  • enhance PgConfig to be able to construct itself from a set of environment variables by @eeeebbbbrrrr in #1019 and #1020

Other Cleanups

New Contributors

Full Changelog: v0.7.0-beta.1...v0.7.0

v0.7.0-beta.1

15 Jan 22:35
90d0fce
Compare
Choose a tag to compare
v0.7.0-beta.1 Pre-release
Pre-release

This is pgx v0.7.0-beta.1. It's a minor update that fixes a few behind-the-scenes issues discovered with beta0. It also starts to improve our cross-compilation story a bit more.

As always, install with cargo install cargo-pgx --version 0.7.0-beta.1 --locked and update your extension crate dependencies accordingly.

What's Changed

  • Fully qualify some use statements emitted by code generation by @eeeebbbbrrrr in #1006
  • feature flags can also be delimited by a comma by @eeeebbbbrrrr in #1008
  • Add the ability for #[pg_extern]-style functions to return Result<Option<SetOfIterator>>. by @eeeebbbbrrrr in #1007
  • Allow overriding the binding generator and work on a better CROSS_COMPILE.md by @thomcc in #1010

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

v0.7.0-beta.0

12 Jan 03:18
f7ca21c
Compare
Choose a tag to compare
v0.7.0-beta.0 Pre-release
Pre-release

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_* ...
Read more

v0.6.1

06 Dec 18:09
Compare
Choose a tag to compare

Welcome to pgx v0.6.1. This is a minor release that fixes a few safety/crashing bugs along with fixing up the --profile argument to cargo pgx.

What's Changed

cleanup cargo-pgx handling of the --profile argument by @eeeebbbbrrrr in #908

v0.6.0 introduced the --profile argument. While it works for any of the targets such as run, test, install, it was primary intended for cargo pgx package so that a specific, "more optimized" release profile could be used. It of course, didn't work and caused cargo to raise an error about conflicting arguments. It now works as expected.

Ensuring owned memory context is not current when dropping it (extension) by @yrashk in #922

@yrashk found a bug that would crash Postgres when Rust drops a PgMemoryContexts::Owned that was also set as the pg_sys::CurrentMemoryContext.

Note that this introduces a minor API breakage as the function PgMemoryContexts::set_as_current() now takes &mut self instead of &self.

Handle panics in PgMemoryContexts::switch_to by @yrashk in #920

@yrashk found another bug that would crash Postgres if a panic occurred while inside a PgMemoryContexts::switch_to(|| ... ) closure.

#[pg_guard] can now be applied to generic functions by @yrashk in #918

Additionally, pgx will emit a compiler error if you try to attach both #[pg_guard] and #[no_mangle] to the same extern "C" function which is generic over anything but a lifetime.

Once again, thanks @yrashk!

Full Changelog: v0.6.0...v0.6.1

v0.6.0

01 Dec 06:39
e460d80
Compare
Choose a tag to compare

This is the full release of pgx 0.6.0!
Remember to rustup update and then cargo install cargo-pgx, but that also brings us to the first two updates!
It's important to remember to update your rustc installation first because the rustc version must be the same as what is used to build cargo pgx and for compiling crates. We now we enforce that thanks to thomcc.
You may now build cargo pgx with rustls thanks to @felipe-vaultree, using:

cargo install cargo-pgx \
  --locked \
  --version 0.6.0 \
  --features rustls

rustls can help if the "native TLS" cargo pgx would default to is OpenSSL.
This is not a comment on OpenSSL's security, only on ease of installing and using it.

New Logo!

Check it out! We added a new logo by Cenza Della Donna!

Logo

Breaking Changes

This version brings a number of breaking changes.

Postgres Major Support

This release introduces support for Postgres 15 and drops support for Postgres 10, thanks to @Smittyvb, @BradyBonnette, @yrashk, and @steve-chavez!

Numeric

Thanks to @eeeebbbbrrrr, proper support for SQL's NUMERIC has landed in PGX, using two types:

  • AnyNumeric
  • Numeric<const P: u32, const S: u32>

Obviously, this breaks code using Numeric as it currently is, which is more like AnyNumeric.

Usage Note: As far as we are able to discern, AnyNumeric is the type used by Postgres on SQL function entry and exit, even if you specify a precision and scale in SQL, so for the case of #[pg_extern] you should probably prefer AnyNumeric, and deliberately convert to Numeric<P, S> inside functions if needed. Numeric<P,S> helps most with serialization, writing to tables, and other cases Postgres also uses strict precision and scale.

Error Handling has been revamped

Error handling has been revamped in a way that may be breaking if you were directly handling PGX's error-handling functions, which are intended to be used when you extend this with your own error-handling abstractions. This includes a lot more support for the kinds of patterns allowed by PG_TRY and PG_CATCH. Take a look at PgTryBuilder.

SpiClient now discourages misuse, plus other Spi* improvements

@yrashk and @thomcc have significantly revised the way that SpiClient works, although a lot of users won't notice a difference. It now uses a scoped lifetime, existing as more of a consumable token, rather than something you can just arbitrarily instantiate. Also see:

  • Ensure SpiClient is only used within boundaries of a connection by @yrashk in #896
  • SpiClient::update no longer requires &mut self by @yrashk in #897
  • Non-leaking, consumable SpiClient by @yrashk in #898
  • Ensure the lifetime of SpiClient is scoped to the connection by @thomcc in #900

BackgroundWorker::transaction fixes

@yrashk expanded the ability of various contexts to allow data to escape them: background workers can return values from transaction, and no longer require Copy to do so.

PgNode is now sealed

This probably won't affect most users, but PgNode is now a "sealed trait", preventing you from implementing it on things. Sorry! PGX relies on the soundness of its implementation, and probably will rely on that more in the future.

PgRelation will promise less

Rust functions that are safe should not cause UB with arbitrary inputs, so @workingjubilee made PgRelation::with_lock unsafe in #886. Thanks to @JohnHVancouver for catching that one!

Deprecated code

Most deprecations that began in 0.5.0 have now been made good on:

  • Array::over is no more 🎉. This will allow us to speed up Array<'a, T> in the future and make it more sound.
  • Most of the ::new functions on datetime types.
    You can still opt in or out of the time crate as a dependency using
pgx = { version = "0.6.0", features = "time-crate" }

This will let you use various TryFrom or From impls.

typo lol

The indicies function now is indices thanks to @jteplitz. This is technically a breaking change!

New in 0.6.0

pgx::datum::Range<T>

We now can map "range types" between Rust and Postgres thanks to @mhov!

pgx now defends against FFI while multithreading

It's now almost reasonable to offload work onto multiple threads while using PGX, as @thomcc gave us a true check for calling FFI from multiple threads that is more resilient to being fooled by renaming threads or other oddness you might get up to. @eeeebbbbrrrr made pg_sys functions also #[track_caller] to help detect and track this. Remember, however, that Postgres is fundamentally single-threaded, so all interaction with Postgres must be on a single thread... and whether PGX functions call into Postgres may change between versions without warning!

  • Include caller location in error message when pgx detects a Postgres FFI was called on a not-the-main-thread by @eeeebbbbrrrr in #862
  • "ereport" messages (pgx::log!(), pgx::error!(), etc) no longer add a CONTEXT message to the ereport by @eeeebbbbrrrr in #875

pgx-pg-sys build improvements

Pertinent to our Postgres version support updates, @BradyBonnette taught pgx-pg-sys how to warn if you use an unsupported version of Postgres.

We also gained some bindings:

  • Include extension & namespace catalogs by @yrashk in #836
  • Add bindings for typedefs within replication/logical.h to pg_sys by @agamble in #827
  • add the catalog/indexing.h header by @eeeebbbbrrrr in #874

Compatibility with various environments

cargo pgx will now configure databases to use C.UTF-8 locale when it creates them (e.g. for testing) thanks to @Smittyvb, or use the "C" locale instead as a fallback.

/And we now also test multiple distros thanks to @BradyBonnette!

Thanks to @pcnc we caught some AArch64 compatibility issues related to c_char.

Miscellaneous Improvements

Most other changes are more subtle quality of life improvements:

Documentation and example updates

A fair amount of PGX documentation got some polish.

  • Update PgTryBuilder docs by @yrashk in #865
  • Provide an example of PostgresType derivation on enums by @yrashk in #861
  • Document pg_extern(name) by @yrashk in #868
  • Thanks to @MaxKingPor we found the macro docs still mentioned impl Iterator! It now recommends TableIterator appropriately. Please let us know if you find any issues with the PGX documentation or have a question!

New Contributors

Full Changelog: v0.5.6...v0.6.0

v0.6.0-alpha.2

18 Nov 21:09
670aaa7
Compare
Choose a tag to compare
v0.6.0-alpha.2 Pre-release
Pre-release

This is pgx v0.6.0-alpha.2. It's mainly a followup to alpha.1 with issues reported from the wild.

What's Changed

New Contributors

  • @pcnc made their first contribution in #870

v0.6.0-alpha.0

12 Nov 00:16
7431028
Compare
Choose a tag to compare
v0.6.0-alpha.0 Pre-release
Pre-release

Welcome to the first prerelease of pgx 0.6.0!
Remember to use cargo install cargo-pgx --version 0.6.0-alpha.0 --locked!

Postgres Major Support

This release introduces support for Postgres 15 and drops support for Postgres 10, thanks to @Smittyvb, @BradyBonnette, @yrashk, and @steve-chavez.

Numeric

Thanks to @eeeebbbbrrrr, proper support for SQL's NUMERIC has landed in PGX, using two types:

  • AnyNumeric
  • Numeric<const P: u32, const S: u32>

Obviously, this breaks code using Numeric as it currently is, which is more like AnyNumeric.

Usage Note: As far as we are able to discern, AnyNumeric is the type used by Postgres on SQL function entry and exit, even if you specify a precision and scale in SQL, so for the case of #[pg_extern] you should probably prefer AnyNumeric, and deliberately convert to Numeric<P, S> inside functions if needed. Numeric<P,S> helps most with serialization, writing to tables, and other cases Postgres also uses strict precision and scale.

Error Handling has been revamped

Error handling has been revamped in a way that may be breaking if you were directly handling PGX's error-handling functions, which are intended to be used when you extend this with your own error-handling abstractions. This includes a lot more support for the kinds of patterns allowed by PG_TRY and PG_CATCH. Take a look at PgTryBuilder.

cargo pgx can use rustls!

You can now configure cargo-pgx to use rustls instead of native SSL, but you must intentionally build it that way for now.

Data can now actually return!

@yrashk expanded the ability of various contexts to allow data to escape them: background workers can return values from transaction, and Spi::connect can now return values without the FromDatum + IntoDatum bound.

Performance with soundness?

pgx-pg-sys build improvements

Pertinent to our Postgres version support updates, @BradyBonnette taught pgx-pg-sys how to warn if you use an unsupported version of Postgres. @thomcc also removed our need for rayon to build. We also gained some bindings:

  • Include extension & namespace catalogs by @yrashk in #836
  • Add bindings for typedefs within replication/logical.h to pg_sys by @agamble in #827

Miscellaneous Improvements

Most other changes are more subtle quality of life improvements:

New Contributors

Full Changelog: v0.5.6...v0.6.0-alpha.0