Postgres extension library for Rust
The main things provided by this crate are some macros that help with writing Postgres extensions in Rust.
The objective (not all these are yet implemented):
pg_magicmacro for declaring libraries as Postgres extensions
pg_externattribute for wrapping Rust functions in Postgres C style definitions
This project uses
cargo-makefor automation. While not necessary, it does help with a lot of the build tasks, so is recommended. This can be installed with
cargo install cargo-make.
Once installed, it will install Postgres into the
targetdirectory for testing. There are profiles for each supported Postgres version,
v12. The specific minor version used is in
To run all tests with all features, for example, run:
> cargo make all-features -p v12 # if -p is left off, then the default is v12
cargo-makethen the environment variable
PG_DIRcan be used to specify the location of the Postgres install.
First install Postgres. The build should be able to find the directory for the Postgres server headers, it uses the
pg_config --includedir-serverto attempt to find the directory. If it is unsuccessful then this environment variable is required:
PG_INCLUDE_PATH=[/path/to/postgres]/include/server # e.g. /usr/local/pgsql/include/server
For the dynamic library to compile, your project should also have
.cargo/configfile with content:
[target.'cfg(unix)'] rustflags = "-C link-arg=-undefineddynamic_lookup"
[target.'cfg(windows)'] rustflags = "-C link-arg=/FORCE"
This informs the linker that some of the symbols for Postgres won't be available until runtime on the dynamic library load.
Standard tests can be run with the normal
cargo test, but the integration tests are a little more involved. They require a connection to an actual Postgres DB. These instructions were performed on macOS. Create a DB in Postgres to be use. In this example a DB was created in the
/usr/local/var/posgrespath, with the name
postgres. When using
cargo-makeall the automation of starting, installing and setting up the DB is handled for you:
Test all features:
> cargo make all-features
Test default features:
> cargo make default-features
> cargo make no-default-features
Testing against different versions;
> cargo make all-features -p v10
To run the test must know the DB name to use, the DB must be running, and then the tests can be run:
pg_ctl -D /usr/local/var/postgres start cargo test
For live discussions beyond this repository, please see this Discord.