PL/Rust: A Trusted Procedural Language Handler for Rust

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.

Documentation

PL/Rust's documentation can be found at https://tcdi.github.io/plrust. Also see the plrust-trusted-pgrx Rust documentation.

Install on Debian today!

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.

Join our Community

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

Quick Example

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 
-----------------
               4

PL/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

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.

Cross Compilation Support

See the Cross compliation section of the documentation for cross-compilation details.

Configuration

See the PostgreSQL Configuration section of the documentation for notes on configuring PL/Rust in postgresql.conf.

---

Lints

See the Lints section of the documentation.

Environment Variables

See the Environment variables section of the documentation.

Quickly Getting Started

To quickly evaluate PL/Rust from this repository...

First, install and initialize the required build environment tools:

$ cargo install cargo-pgrx --locked
$ cargo pgrx init

Then 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> \q

Apply 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}'
EOF

Finally, 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 
-----------------
               4

Other Notes

In 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.

Security Notice

Please read the Security for directions on reporting a potential security issue.

License

PL/Rust is licensed under "The PostgreSQL License", which can be found here.