PL/Rust is a loadable procedural language that enables writing PostgreSQL functions in the Rust programming language. These functions are compiled to native machine code. Unlike other procedural languages, PL/Rust functions are not interpreted.
The primary advantages of PL/Rust include writing natively-compiled functions to achieve the absolute best performance, access to Rust's large development ecosystem, and Rust's compile-time safety guarantees.
PL/Rust provides access to Postgres' Server Programming Interface (SPI) including dynamic queries, prepared
statements, and cursors. It also provides safe Rust types over most of Postgres built-in data types, including (but
not limited to), TEXT, INT/BIGINT, NUMERIC, FLOAT/DOUBLE PRECISION, JSON/JSONB, arrays, and more. You can also use PL/Rust to write trigger functions.
On x86_64 and aarch64 Linux systems PL/Rust can be a "trusted" procedural language, assuming the proper compilation requirements are met. On other systems, it is perfectly usable as an "untrusted" language but cannot provide the same level of safety guarantees.
PL/Rust's documentation can be found at https://tcdi.github.io/plrust. Also see the
plrust-trusted-pgrx Rust documentation.
Head on over to the PL/Rust releases page to get the latest release and check out the documentation page to get started with PL/Rust.
The PL/Rust team at TCDI manages a Discord server where we discuss PL/Rust and related technologies
such as pgrx, Rust, and Postgres. Feel free to join: https://discord.gg/mHKrj55zyh
An example PL/Rust function:
psql> CREATE FUNCTION add_two_numbers(a NUMERIC, b NUMERIC) RETURNS NUMERIC STRICT LANGUAGE plrust AS $$
Ok(Some(a + b))
$$;
psql> SELECT add_two_numbers(2, 2);
add_two_numbers
-----------------
4PL/Rust itself is a pgrx-based Postgres extension. Furthermore, each LANGUAGE plrust function are themselves mini-pgrx extensions. pgrxis a generalized framework for developing Postgres extensions
with Rust. Like this project, pgrx is developed by TCDI.
The following sections discuss PL/Rusts safety guarantees, configuration settings, and installation instructions.
Installing PL/Rust and especially postgrestd requires a normal installation of Rust via
rustup and for the relevant locations to be writeable on the building host.
See the Install PL/Rust
section of the documentation for notes on installing PL/Rust and its dependencies.
Debian packages are also available -- see the documentation page for installation instructions.
See the Cross compliation section of the documentation for cross-compilation details.
See the PostgreSQL Configuration
section of the documentation for notes on configuring PL/Rust in
postgresql.conf.
See the Lints section of the documentation.
See the Environment variables section of the documentation.
To quickly evaluate PL/Rust from this repository...
First, install and initialize the required build environment tools:
$ cargo install cargo-pgrx --locked
$ cargo pgrx initThen clone this repository and build/run PL/Rust once to complete the cargo-pgrx environment initialization:
$ git clone https://github.com/tcdi/plrust.git
$ cd plrust
# build plrustc, our custom rustc driver and copy it to ~/.cargo/bin
$ cd plrustc && ./build.sh
$ cp ../build/bin/plrustc ~/.cargo/bin
# build and run plrust itself
$ cd ../plrust/plrust
$ cargo pgrx run pg14 --release
# which drops you into a psql shell. just \quit it for now
psql> \qApply the required postgresql.conf configuration:
$ SCRATCH_DIR=${HOME}/plrust-scratch
$ mkdir -p ${SCRATCH_DIR}
$ cat <<-EOF >> ~/.pgrx/data-14/postgresql.conf
shared_preload_libraries = 'plrust'
plrust.work_dir = '${SCRATCH_DIR}'
EOFFinally, run it for real and start writing functions!
$ cargo pgrx run pg14
psql> CREATE EXTENSION plrust;
psql> CREATE FUNCTION add_two_numbers(a NUMERIC, b NUMERIC) RETURNS NUMERIC STRICT LANGUAGE plrust AS $$
Ok(Some(a + b))
$$;
psql> SELECT add_two_numbers(2, 2);
add_two_numbers
-----------------
4In the Postgres world it seems common for procedural languages to have two styles, "trusted" and "untrusted". The consensus is to name those as "lang" and "langu", respectively -- where the "u" is supposed to represent "untrusted" (see "plperl" v/s "plperlu" for example).
PL/Rust does not do this. The only thing that Postgres uses to determine if a language handler is considered "trusted" is if it was created using CREATE TRUSTED LANGUAGE. It does not inspect the name.
PL/Rust stores user functions in pg_catalog.pg_proc's prosrc field as a complex json structure where the compiled
function is a compressed, base64 encoded string, with the key-value pairs mapping each target tuple to compiled object code.
As such, compiling a function with an "untrusted" version of PL/Rust, then installing the "trusted" version and trying to run that function will fail -- "trusted" and "untrusted" are considered different compilation targets and are not compatible with each other, even if the underlying hardware is exactly the same.
This does mean that it is not possible to install both "trusted" and "untrusted" versions of PL/Rust on the same Postgres database cluster.
In the future, as postgrestd is ported to more platforms, we will seriously consider having both plrust and plrustu. Right now, since "trusted" is only possible on Linux x86_64/aarch64, our objective is to drive production installations to be "trusted", while allowing non-Linux developers the ability to use LANGUAGE plrust too.
Please read the Security for directions on reporting a potential security issue.
PL/Rust is licensed under "The PostgreSQL License", which can be found here.