pg-extend-rs

by bluejekyll

bluejekyll / pg-extend-rs

Postgres extension library for Rust

243 Stars 27 Forks Last release: Not found Other 169 Commits 0 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Build Status License: MIT License: Apache 2.0 Dependabot Status Discord

Rust based Postgres extension

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):

  • Automatic type conversions, see
    PgDatum
    and
    TryFromPgDatum
    to
    Into
  • pg_magic
    macro for declaring libraries as Postgres extensions
  • pg_extern
    attribute for wrapping Rust functions in Postgres C style definitions
  • panic handlers for conversion into Postgres errors
  • allocator that uses Postgres
    palloc
    allocator and
    pfree
  • tbd integrate postgres error logs with
    log
  • tbd support all Datum types
  • tbd support table like returns and manipulation
  • tbd generators for the psql scripts to load functions

Getting started

This project uses

cargo-make
for 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

target
directory for testing. There are profiles for each supported Postgres version,
v10
,
v11
, and
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

Building

If using

cargo-make
then the environment variable
PG_DIR
can 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-server
to 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/config
file 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.

Running the integration tests

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/posgres
path, with the name
postgres
. When using
cargo-make
all 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

Test no-default-features:

> cargo make no-default-features

Testing against different versions;

v10
,
v11
,
v12
are valid:
> cargo make all-features -p v10

Without cargo-make

To run the test must know the DB name to use, the DB must be running, and then the tests can be run:

export POSTGRES_TEST_DB=postgres

pg_ctl -D /usr/local/var/postgres start cargo test

Examples

Features

TBD

Community

For live discussions beyond this repository, please see this Discord.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.