Skip to content

How To Contribute

This project is an open project. Any comment or idea is more than welcome.

Here's a few tips to get started if you want to get involved

Where to start ?

If you want to help, here's a few ideas :

1- Testing: You can install the latest branch of the project and realize extensive tests based on your use case. This is very useful to improve the stability of the code. Eventually if you can publish you test cases, please add them in the /tests/sql directory or in demo. I have recently implemented "anonymous dumps" and I need feedback !

2- Documentation: You can write documentation and examples to help new users. I have created a docs folder where you can put documentation on how to install and use the extension...

3- Benchmark: You run tests on various setups and measure the impact of the extension on performances

4- Junior Jobs: We may flag a few issues as "Junior Jobs" on the project issue board. If you want to give a try, simply fork the git repository and start coding !

5- Spread the Word: If you look this extension, just let other people know ! You can publish a blog post about it or a youtube video or whatever format you feel comfortable with !

In any case, let us know how we can help you moving forward

Set up a development environment

This extension is written in SQL, pl/pgsql and Rust. It relies on a Rust framework named PGRX.

To set up, your development environment follow the PGRX install instructions !

You can also install additional tools for linting, code coverage and SBOM generation.

cargo install uv grcov cargo-cyclonedx

Testing

We use 4 levels of testing:

  • Rust unit tests are implemented directly in source files using the #[test] attribute. They are the simple and fast. You can run them with make test

  • PGRX unit tests are also implemented in the code using #[pg_test] attribute. They required a running Postgres instance which makes them slower. You can run them with make test

  • regression tests are functional tests written in SQL and located in the tests/pg_regress/sql folder. You can run them with make regress

  • end-to-end tests are simulation of an application using the extension. You can run them with make end2end

Debug mode

By default, the extension is built with the Rust --release mode.

For a more verbose output, you can enable the debug mode with

TARGET=debug make run

In CI, the extension is built with the release mode, which means that the DEB and RPM packages are also in release mode.

Build the docs

The documentation is automatically published on readthedocs.io, but you can build it locally with:

make docs
cd site

We publish 2 versions of the documentation stable and latest.

If you want to read the documentation of a previous version, you can simply read the markdown files in the docs folder :

# replace `0.1.0` with the version you want
git checkout 0.1.0
make docs
cd site

Linting

Use make lint to run the various linters on the project.

Git pre-commit hook

We maintain a [pre-commit] configuration to operate some verification at commit time, if you want to use that configuration you should:

uvx prek install

Compatibility with ARM

We do not provide community support for this extension on ARM64 architectures.

However some people have successfully build the extension for ARM64 and here's some good practice to maintain compatibility.

On some ARM platforms a "char" is actually an "unsigned integer" (u8) while on AMD64 it is a signed integer (i8). To avoid compilation errors, we use the std::os::raw::c_char type instead of i8, especially for C char pointers.

For example:

let belt = belt_cstr.as_ptr() as *const i8;

becomes

use std::os::raw::c_char;
let belt = belt_cstr.as_ptr() as *const c_char;

Benchmark

At anytime, we can run a series of benchmarks to check if some recent changes may introduce performance regression.

First run a benchmarks on the latest branch for reference

git checkout latest
cargo pgrx bench --group-name latest

... then switch to the new branch (here "foo") and run the bench again

git checkout foo
cargo pgrx bench --group-name foo-1

We can then ask for a report with:

cargo pgrx bench --report
````

See `cargo pgrx bench --help` and the [PGRX] documentation for more details


Warnings about unstable input conversion
-------------------------------------------------------------------------------

When developing with PGRX, you might encounter warnings like this:

``` sql
SELECT 'hello'::tcetext::text;
WARNING:  type tcetext has unstable input conversion for "hello"
LINE 1: SELECT 'hello'::tcetext::text;

These warnings happen because pgrx builds its PostgreSQL instances with the RANDOMIZE_ALLOCATED_MEMORY enabled (a compile time flag, not a GUC). Among other things, that flag triggers a test in the coerce_type function. That test calls every input function twice to check the result is stable.

This test makes sense for most types. In general, a type input function should be stable. However for TCE types, we use a nonce (a random number used only once) so that for a given plaintext value, its ciphered representation on disk is always different and unpredictable. In other words, the input functions of the TCE types are not homomorphic, thus they are not stable.

Which means that any data inserted into a TCE column or converted into a TCE type will trigger the warning above. The warning will also appear all over in the regression tests.

That warning however is NOT present in production because the flag RANDOMIZE_ALLOCATED_MEMORY is disabled on most PostgreSQL instances.

This also means that since the input functions are called twice, the performances on the pgrx-managed instances will be much worse than in production and that any benchmark ran on a pgrx instance is not representative of the effective response times in production.

Publishing a new Release

See .gitlab/issue_templates/Release.md