Rust Guide (original) (raw)

This section provides steps on how to proceed with installing PL/Rust. There are three ways to install PL/Rust. Most users will want to install trusted PL/Rust.

These instructions assume you have followed the Install Prerequisitessection and are logged in as the postgres Linux user. Install PL/Rust by following the installation steps under your method of choice below. Then visitthe configuration subsectionand give PL/Rust a try!

Untrusted install

To install untrusted PL/Rust use cargo pgrx installwithout --features trusted. See the trusted install if you wish to install the trusted PL/Rust instead.

cargo pgrx install --release -c /usr/bin/pg_config

Continue on to configuring PostgreSQLfor PL/Rust.

Trusted install

The trusted installation requires postgrestd and a few additional Rust dependencies. First install the additional dependencies. This example uses x86_64 and ensures the target is installed. If you are using aarch64, update the command accordingly.

Linux:

rustup component add llvm-tools-preview rustc-dev
rustup target install x86_64-unknown-linux-gnu

macOS:

rustup component add llvm-tools-preview rustc-dev
rustup target install x86_64-apple-darwin

Change into the plrust/plrustc directory to build plrustc. Move the generated binary into ~/.cargo/bin/.

cd ~/plrust/plrustc
./build.sh
mv ~/plrust/build/bin/plrustc ~/.cargo/bin/

Note: The path ~/.cargo/bin/ is the default path used by PL/Rust. This can be overridden using plrust.PATH_override, see PostgreSQL Config.

Change into the plrust/plrust/ directory and run the build process to install postgrestd. This example is for installing PL/Rust on x86_64architecture, switch to aarch64 if using that architecture instead.

cd ~/plrust/plrust
PG_VER=15 \
    STD_TARGETS="x86_64-postgres-linux-gnu " \
    ./build

The above step can take quite a few minutes to install postgrestd and run the associated tests. It is not uncommon to see output like the following during the test process.

test tests::tests::pg_plrust_aggregate has been running for over 60 seconds

The final step for trusted PL/Rust installation is to usecargo pgrx install with --features trusted.

cargo pgrx install --release --features trusted -c /usr/bin/pg_config

Continue on to configuring PostgreSQLfor PL/Rust.

Choosing a different plrust-trusted-pgrx dependency at compile time

When a user creates a LANGUAGE plrust function, PL/Rust first generates a small Cargo crate for the function. That crate has a dependency on plrust-trusted-pgrx. By default, plrust-trusted-pgrx comes from crates.io, using the same version as PL/Rust itself.

It is possible to override this dependency when compiling PL/Rust itself so that PL/Rust will use a differentplrust-trusted-pgrx crate. To do this, set an environment variable named PLRUST_TRUSTED_PGRX_OVERRIDE to the full "Cargo.toml"-compatible dependency line, like so:

PLRUST_TRUSTED_PGRX_OVERRIDE="pgrx = { path = '~/code/plrust/plrust-trusted-pgrx', package='plrust-trusted-pgrx' }" \
cargo pgrx install --release --features trusted -c /usr/bin/pg_config

This will instead compile all user functions using this specific plrust-trusted-pgrx, not the default on crates.io. Generally, changing the plrust-trusted-pgrx dependency is only useful for PL/Rust development and CI, not for production deployments, but is worth mentioning as the environment variable will influence how user functions are compiled.

It may also be useful for providing a local patch to plrust-trusted-pgrx if such a need were to arise.

Trusted installation plus cross compilation

Adding cross compilation support to PL/Rust requires a few minor changes to thetrusted installation steps above. This section only highlights the changes to make for cross compile support, not the full process.

Linux

As a Linux user with sudo access, install these additional prerequisites.

sudo apt install crossbuild-essential-arm64 crossbuild-essential-amd64

The normal trusted install uses rustup to install one architecture target. Cross compilation support requires both.

rustup component add llvm-tools-preview rustc-dev
rustup target install aarch64-unknown-linux-gnu
rustup target install x86_64-unknown-linux-gnu

macOS

The normal trusted install uses rustup to install one architecture target. Cross compilation support requires both.

rustup component add llvm-tools-preview rustc-dev
rustup target install aarch64-apple-darwin
rustup target install x86_64-apple-darwin

The above environment variables are the default... you can just run ./build. PG_VER=15 currently represents the latest released PostgreSQL version.

Configure and restart PostgreSQL

The PostgreSQL configuration in postgresql.conf must be updated for PL/Rust to function. This section illustrates the minimum required changes so PL/Rust will function. See the PostgreSQL configuration section for more configuration details.

PL/Rust requires shared_preload_libraries includes plrust and that you define plrust.work_dir.

NOTE: PL/Rust with cross compilation support also requires plrust.compilation_targets.

Edit the PostgreSQL configuration file still as the postgres Linux user.

nano /etc/postgresql/15/main/postgresql.conf

Update the configuration with these items. Note that shared_preload_librariesmight already be set with a value before you add plrust. Use a comma separated list of extensions to include multiple libraries in this configuration option.

shared_preload_libraries = 'plrust'
plrust.work_dir = '/tmp'

The PostgreSQL service needs to be restarted for the configuration changes to take effect. Exit the postgres user and restart the PostgreSQL service.

exit
sudo systemctl restart postgresql

Reset permissions

In order to install the PL/Rust extension as the postgres users permissions were updated in the Permissions sectionof the Install PL/Rust Prerequisites section. Change the permissions for the extension and lib folders back to being owned by the root user.

sudo chown root -R /usr/share/postgresql/15/extension/
sudo chown root -R /usr/lib/postgresql/15/lib/

Try it out

Create a plrust database and connect to the plrust database using psql.

PL/Rust only supports databases encoded as UTF8. This is to ensure proper compatibility between Postgres/SQL TEXT(and internal strings) and Rust String and &str types.

sudo -u postgres psql -c "CREATE DATABASE plrust WITH ENCODING = 'utf8' TEMPLATE = 'template0';"
sudo -u postgres psql -d plrust

Create the plrust extension.

CREATE EXTENSION plrust;

If you installed the untrusted PL/Rust you will be warned of that detail in this step.

WARNING:  plrust is **NOT** compiled to be a trusted procedural language

The following example creates a plrust function named plrust.one()that simply returns the integer 1.

CREATE OR REPLACE FUNCTION plrust.one()
    RETURNS INT LANGUAGE plrust
AS
<span class="katex-display"><span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mi>O</mi><mi>k</mi><mo stretchy="false">(</mo><mi>S</mi><mi>o</mi><mi>m</mi><mi>e</mi><mo stretchy="false">(</mo><mn>1</mn><mo stretchy="false">)</mo><mo stretchy="false">)</mo></mrow><annotation encoding="application/x-tex">Ok(Some(1))</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:1em;vertical-align:-0.25em;"></span><span class="mord mathnormal" style="margin-right:0.02778em;">O</span><span class="mord mathnormal" style="margin-right:0.03148em;">k</span><span class="mopen">(</span><span class="mord mathnormal" style="margin-right:0.05764em;">S</span><span class="mord mathnormal">o</span><span class="mord mathnormal">m</span><span class="mord mathnormal">e</span><span class="mopen">(</span><span class="mord">1</span><span class="mclose">))</span></span></span></span></span>;

Using a function created with PL/Rust is the same as using any other PostgreSQL function. A scalar function like plrust.one() can be used simply like below.

SELECT plrust.one();

┌─────┐
│ one │
╞═════╡
│   1 │
└─────┘