v1.1.1

This is PL/Rust v1.1.1. It contains no code changes itself, but picks up the latest version of pgrx (v0.8.2), which fixes a bug with arrays and also generally improves build times.

It also fixes the Dockerfile.try to use pgrx, instead of the old name "pgx".

Enjoy!

v1.1.0

Welcome to PL/Rust v1.1.0. It is primarily a bugfix release in response to issues created and noticed immediately after v1.0.0.

New Features

Zero Copy Arrays by @eeeebbbbrrrr in #298

When a LANGUAGE plrust function has an ARRAY argument, it is now treated as a pgrx::Array, which is a zero-copy wrapper over the underlying Postgres ArrayType.

The primary change here is that v1.0.0 used a Vec<T>, so it provided random access into the array at the expense of deconstructing the whole thing ahead of time. pgrx::Array is essentially a lazy Iterator with some convenience methods like .len(). If you need random access into the array, you'll need to collect into a Vec<Option<T>> first:

CREATE OR REPLACE FUNCTION array_nth(a int[], i int) 
          RETURNS int 
          IMMUTABLE
          STRICT 
          LANGUAGE plrust AS 
$$
   let a = a.into_iter().collect::<Vec<_>>();
   Ok(a[i as usize])
$$;

SELECT array_nth(ARRAY[1,2,3,4,5,6,7,8,9,10], 5);
 array_nth 
-----------
         6

Existing functions based on PL/Rust v1.0.0 will continue to compile unchanged during a pg_dump/pg_reload cycle, but users should consider updating their function code and re-creating them with CREATE OR REPLACE FUNCTION.

Bug Fixes

Purposely fail to create on databases that aren't UTF8 by @eeeebbbbrrrr in #281

PL/Rust can only support databases that are UTF8 encoded and going forward PL/Rust will fail during CREATE EXTENSION if this is isn't the case.

It is possible in the future we can lift or greatly lessen this restriction

Incorrect type mappings by @eeeebbbbrrrr in #299

A few SQL types were incorrectly mapped to Rust types at either the argument or return type positions. The changes are:

• BYTEA is now returned as a Vec<u8>
• CSTRING is now a &CStr at the argument position and a CString at the return type position
• TID is now a pg_sys::ItemPointerData in both argument and return positions

General Project Cleanup

Add Dockerfile for quick trial use by @BradyBonnette in #287

See the documentation to quickly try PL/Rust within a Docker container!

While not at all a production-worthy Dockerfile, our hope is that it'll be easy for newcomers to interactively try PL/Rust.

AnyNumeric now supports the std::iter::Sum trait pgcentralfoundation/pgrx#1117

Functions that use NUMERIC can now easily sum an array/iterator of them:

 CREATE FUNCTION sum_array(a NUMERIC[]) RETURNS NUMERIC
          IMMUTABLE 
          STRICT
          LANGUAGE PLRUST AS
$$
   Ok(Some(a.into_iter().map(|v| v.unwrap_or_default()).sum()))
$$;

SELECT sum_array(ARRAY[1, 2.0, 3.5]);
 sum_array 
-----------
       6.5

Other Minor Changes

• Make GitHub recognize the PostgreSQL license by @gurjeet in #292
• fix issue #279: compilation warning by @eeeebbbbrrrr in #300
• Updates to use pgrx. by @eeeebbbbrrrr in #294, #297

Documentation

• Update create function examples to include REPLACE for easy copy/paste. by @SeanOzzy in #286
• Docs updates by @eeeebbbbrrrr in #288
• README.md cleanups: by @eeeebbbbrrrr in #289
• Fixes up a few Docker documentation issues by @BradyBonnette in #291

New Contributors

• @SeanOzzy made their first contribution in #286
• @gurjeet made their first contribution in #292

Full Changelog: v1.0.0...v1.1.0

v1.0.0

We are excited to present PL/Rust v1.0.0. Writing Postgres UDFs in Rust has never been easier (mostly because it hasn't been possible)!

PL/Rust is a loadable, trusted procedural language handler enabling developers to create PostgreSQL functions in the Rust programming language. Unlike other procedural languages, PL/Rust functions are not interpreted. Instead, the definition you supply to CREATE FUNCTION ... LANGUAGE plrust is wrapped in Rust, compiled to native machine code, and dynamically loaded.

Many of the usual tradeoffs of compilation apply:

• Compilation can be slow
• Execution can be very fast, often ×10 faster than PL/pgSQL!
• Types are static and must be explicitly handled
• Code can be fully analyzed and errors caught at compile time
• PL/Rust must understand both what it compiles and how to compile, so 1.0 currently only supports some Postgres types and Rust targets

However, many other burdens of compiling native ("C") functions are removed. PL/Rust can transparently reload, recompile, and replace functions without additional prompting, as if it was any other procedural language. Documentation, while still under development, can be found here: https://tcdi.github.io/plrust/

Please feel free to open an issue if you have any additional questions!

Platform Support

• x86-64 and aarch64 Linux are supported for host compilation with Postgres 13, 14, and 15
• Cross-compiling between x86-64 and aarch64 for replication purposes may be enabled with the latest update of Debian Bullseye using a Rust toolchain obtained from https://rustup.rs and other setups may be enabled by user configuration on other distributions
• Trusted PL/Rust is supported for Rust 1.67.1
• Untrusted PL/Rust may be built for development purposes on macOS

Thanks Everyone!

We want to make sure to properly thank all the past (and hopefully future!) PL/Rust contributors. Without their work, PL/Rust wouldn't exist. Thank you! 🙏

Also, a huge thanks to TCDI for funding this work and putting together an absolutely outstanding team.

What's Changed Since v1.0.0-rc.1

plrustc Lints

• Add a lint to plug autotrait impl soundness hole by @thomcc in #263
• Add a lint for 'static impl shenanigans by @thomcc in #265
• Add a lint for certain suspicious trait object usage by @thomcc in #264
• Enable the where_clauses_object_safety lint by default by @thomcc in #268
• Use early_error to emit early errors by @thomcc in #272
• Move lints into their own file by @thomcc in #271

Documentation

• Cleanup readme for items moved to docs by @rustprooflabs in #266
• Docs: Intro, Cross compile install, and Configuration cleanup by @rustprooflabs in #274

Miscellaneous Niceties

• Only set -Clink-args=-Wl,-undefined,dynamic_lookup on macos by @thomcc in #273
• Ability to decide, at compile time, which "plrust-trusted-pgx" crate user functions should use by @eeeebbbbrrrr in #276

Full Changelog: v1.0.0-rc.1...v1.0.0

v1.0.0-rc.1

This is the second PL/Rust 1.0 release candidate. Notably, it contains a number of safety fixes.

If installing for the first time or updating from a previous release candidate, you'll need to install plrustc and postgrestd as described in the documentation.

PL/Rust documentation is still a work-in-progress, but is now automatically published to https://tcdi.github.io/plrust/.

Safety Fixes

• Remove RUSTC_WRAPPER from the env if set by @thomcc in #241
• Enable a few non-plrust lints by default, and add a lint for std::io::{stdout, stderr, stdin} by @thomcc in #243
• plrustc: Use custom FileLoaders to sanitize include error messages by @thomcc in #250
• Fix several issues with lint application and detection by @thomcc in #253
• Fix path traversal bug by @thomcc in #259
• Correctly expand args given to plrustc by @thomcc in #252

Documentation Updates

• Remove some stale documentation from plrustc's readme, and add mention of some of the env vars it uses to the main readme by @thomcc in #237
• Add caveat around security/soundness to README.md by @thomcc in #242
• Reorganize and fill out documentation by @rustprooflabs in #171
• Fix docs.rs for plrust-trusted-pgx (hopefully) by @thomcc in #244
• Documentation: Improve installation section by @rustprooflabs in #254
• Documentation: Improve usage by @rustprooflabs in #256
• Document #255 by @rustprooflabs in #260
• Documentation - Logging and Triggers by @rustprooflabs in #246

Testing/CI

• Fix failing uitests and add them to CI by @thomcc in #238
• Adds workflow_dispatch to CI by @BradyBonnette in #261
• Add GitHub workflow to deploy mdbook docs to GitHub pages by @rustprooflabs in #247

Miscellaneous

• Avoid linking to rust-lang/rust's issue tracker if plrustc panics by @thomcc in #251
• Remove pointless build.rs from plrustc by @thomcc in #239
• Add ./build.sh install as a method of installing plrustc (uses cargo install to perform the installation) by @thomcc in #240
• Fix issue #255 by @eeeebbbbrrrr in #258

New Contributors

• @rustprooflabs made their first contribution in #171

Full Changelog: v1.0.0-rc.0...v1.0.0-rc.1

v1.0.0-rc.0

This is plrust's first release candidate!

As things stand now, the code is frozen. Only major bugs, security issues, and documentation will be changed between now and the final release.

Documentation is being worked on as part of PR #171.

Major Changes

• plrust linting via plrustc custom driver by @thomcc in #198

  • Lint uses of include_str/include_bytes by @thomcc in #214
  • Block function pointers via a lint by @thomcc in #216
  • Block async/await via a lint by @thomcc in #217
  • Allow disabling linting when it is set to an empty string by @JohnHVancouver in #219
  • Lint against leaky functions by @thomcc in #224
  • Lint against include!, env!, option_env!, and external modules as well by @thomcc in #220
  • Lint against dyn Fn{,Mut,Once} by @thomcc in #226
  • Add a lint for the print! family of macros by @thomcc in #228
  • Cleanup/rewrite plrustc main.rs by @thomcc in #229
  • Integrate plrustc lints by @eeeebbbbrrrr in #207

• Teach trusted-pgx and plrust about more pgx-supported data types. by @eeeebbbbrrrr in #213

  • This did lead to disabling date/time support for now. pgx needs improved support before these types will be usable by plrust

• Rename trusted-pgx to plrust-trusted-pgx by @eeeebbbbrrrr in #232

  • Allows us to version and update a plrust user function's dependency on pgx independently of plrust and pgx

Bug Fixes

• Fix issue #200 - RETURNS SETOF now works by @eeeebbbbrrrr in #202
• Add newline before closing block by @thomcc in #230
• fix issue #204: pg_restore works by @eeeebbbbrrrr in #212
• address issue #197 by blocking RETURNS TABLE, OUT and INOUT function argument by @eeeebbbbrrrr in #235

General Cleanup

• Remove MacOS-specific "generation" by @eeeebbbbrrrr in #196
• Rewrite TcpStream test by @workingjubilee in #225
• Verify postgrestd::net::TcpStream can't connect by @workingjubilee in #211
• Add pgx::log by @JohnHVancouver in #221
• Remove unused pgx feature flags by @workingjubilee in #227
• Stop using LTO to build function crates by @workingjubilee in #215

Documentation

• tidy up what we expose in docs for trusted-pgx by @eeeebbbbrrrr in #231
• document environment variables... by @eeeebbbbrrrr in #199

Full Changelog: v1.0.0-beta.1...v1.0.0-rc.0

v1.0.0-beta.1

No functional changes here. Simply updated crate dependencies, including pgx to v0.7.1, which gets more Rust math support for the AnyNumeric type.

What's Changed

• Upgrade dependencies by @eeeebbbbrrrr in #194
• Add a test for include_str! by @thomcc in #192

Full Changelog: v1.0.0-alpha.0...v1.0.0-beta.1

v1.0.0-alpha.0

This is the first alpha release for plrust. We're heading towards final v1.0.0 release!

Outside of possible bugfixes or security issues, we believe plrust is in a solid state for a first release. The largest "known issue" is the complete lack of documentation. This is being worked on in PR #171.

Since v0.7.0, the list of changes include...

What's Changed

• plrust functions now return Result<Option<T>> by @eeeebbbbrrrr in #158

This is probably the biggest change, but it allows plrust function authors to more easily work with Spi, especially in the simple cases. Any Result<T, E> type can be returned so long as the T is where IntoDatum and the E is where Display.

• get rid of our custom plrust.plrust_proc by @eeeebbbbrrrr in #173

plrust no longer stores compiled functions in an extension table. Instead, they're stored directly in the prosrc column of pg_catalog.pg_proc.

• Remove the plrust.pg_config GUC by @eeeebbbbrrrr in #181

Configuration no longer requires the plrust.pg_config setting. We can get the information we need to compile user functions directly from the running Postgres instance.

• Set a $PATH when there isn't one by @eeeebbbbrrrr in #193

In order to compile user functions, plrust needs cargo and (at least) cc on the system PATH. If the PATH is unset (or blank), plrust will create its own as ~/.cargo/bin:/usr/bin. This assumes that the rust toolchain is installed by the user running Postgres, which is typically the user postgres.

If this generated path, or the inherited system PATH is not sufficient, it can be overridden using the new plrust.PATH_override GUC.

Cross Compilation Cleanups

• Only specify CARGO_TARGET_..._LINKER if not already specified, and ensure it and STD_TARGETS are exported and avaliable to ./run. by @thomcc in #175

Bug Fixes

• Simplify echo to cargo -vV by @workingjubilee in #176
• Test #[export_name] is blocked by @workingjubilee in #177
• Cleanup source crate after compilation fails by @JohnHVancouver in #184
• Ignore Err if remove_dir_all fails by @workingjubilee in #188
• fix issue #183: Always ensure to call the previous "process utility hook" by @eeeebbbbrrrr in #185
• working on improving the README by @eeeebbbbrrrr in #170
• Fix some broken code in the README by @thomcc in #191

CI Improvements

• Installs cargo-pgx from that defined in plrust/Cargo.toml by @BradyBonnette in #182

New Contributors

• @thomcc made their first contribution in #175

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

v0.7.0-beta.1

This is PL/Rust v0.7.0-beta.1. It's the first release in awhile and the version number is arbitrary, so right now it matches the version of pgx necessary to build it.

Since the last release, many things have changed, and these release notes are going to be a little light as we're still working on improving all of the documentation.

That said, the full set of changes include...

• Store compiled shared object files in a new extension table by @eeeebbbbrrrr in #122
• Crate-wide #![deny(unsafe_op_in_unsafe_fn)] by @workingjubilee in #123
• Reload function.so when the function changes by @eeeebbbbrrrr in #124
• Now #![forbid(unsafe_op_in_unsafe_fn)] by @workingjubilee in #125
• Provide allow_list of dependencies by @JohnHVancouver in #103
• Catch #[no_mangle] by @workingjubilee in #128
• Turn us into a workspace by @eeeebbbbrrrr in #131
• Enable #[link_section] test by @workingjubilee in #135
• Remove geiger by @workingjubilee in #134
• Diet of WORMs by @workingjubilee in #143
• Rename user_crate files by @workingjubilee in #144
• Terse docs for mod user_crate by @workingjubilee in #146
• Add security reporting document by @johnrballard in #147
• Change to use the pgx:develop branch by @eeeebbbbrrrr in #150
• use pg_identify_object() value as the pkey for plrust.plrust_proc by @eeeebbbbrrrr in #141
• fix issue #78 by @eeeebbbbrrrr in #151
• fix issue #79 by @eeeebbbbrrrr in #152
• Fix up PL/Rust for pg_sys::Oid redesign by @workingjubilee in #153
• Introduce a trusted-pgx module by @eeeebbbbrrrr in #142
• upgrade to pgx v0.7.0-beta.0 by @eeeebbbbrrrr in #154
• fix compilation on pg15 by @eeeebbbbrrrr in #157
• CI updates for Postgres 15 by @BradyBonnette in #120
• Declare postgres as vendor in tuples by @workingjubilee in #159
• Work on cross-compilation support by @eeeebbbbrrrr in #155
• On Linux, dlopen() user functions from a memory-mapped file by @eeeebbbbrrrr in #161
• upgrade pgx dependency to 0.7.0-beta.1 by @eeeebbbbrrrr in #164
• Rip out sleepy_boi test by @workingjubilee in #167
• PL/Rust is now a "trusted procedural language" by @eeeebbbbrrrr in #165 & #166

Please pardon the terseness. As said above, we're working on greatly improved documentation. In the mean time you might find the issue descriptions for #165 and #142 interesting.

Full Changelog: plrust-0.0.0-pgx-0.6.0-alpha.1-rustc-1.61.0...v0.7.0-beta.1

plrust-0.0.0-pgx-0.6.0-alpha.1-rustc-1.61.0

Adventure? Excitement? A Jedi craves not these things.

...Jedi do not use this software.

Still alpha quality, currently only suitable for highly experimental usage. Remember!

THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS,

PL/Rust compatible with

• pgx 0.6.0-alpha.1
• rustc 1.61.0
• postgrestd sharing this version tag