Getting ProvSQL

There are three ways to run ProvSQL:

Installing from Source (recommended) – full-featured, suitable for production use and development.
Via PGXN – the PostgreSQL Extension Network wraps the source build behind a one-line pgxn install provsql command.
Docker Container – no installation required, ideal for quickly trying ProvSQL without modifying your system.

Tip

Just want to try ProvSQL without installing anything? The ProvSQL Playground runs PostgreSQL, ProvSQL and ProvSQL Studio entirely in your browser (WebAssembly) at provsql.org/playground/, on demo databases. It needs a recent browser with WebAssembly JSPI; the Playground’s landing page lists current browser support. For real use, install locally as below.

Installing from Source

This is the recommended approach. It gives full access to all features, including external knowledge-compilation tools.

Getting the Source

Releases are available on the ProvSQL website and on the GitHub releases page. The source repository is hosted at https://github.com/PierreSenellart/provsql.

To clone the development version directly:

git clone https://github.com/PierreSenellart/provsql.git

Prerequisites

PostgreSQL ≥ 10. ProvSQL has been tested with versions 10–18 under Linux, macOS (x86-64 and ARM), and Windows Subsystem for Linux.
Build tools. make, a C/C++ compiler supporting C++17, and PostgreSQL development headers (e.g., postgresql-server-dev-XX on Debian-based systems, or the postgresql Homebrew formula on macOS).
uuid-ossp PostgreSQL extension (included with most PostgreSQL packages; compile contrib/ when building from source).
Boost libraries – libboost-dev and libboost-serialization-dev (Debian/Ubuntu), or equivalent.
(Optional) Knowledge-compilation tools for probability computation:
- c2d
- d4 and its rewrite d4v2
- dsharp
- minic2d (also requires hgr2htree)
- Panini (KCBox)
- weightmc, Ganak, SharpSAT-TD, DPMC (weighted model counters)
All of these are optional: ProvSQL ships with an in-process tree-decomposition compiler that needs no external binary. One of the compilers is, however, the final-fallback compiler for probability_evaluate (default d4, configurable via provsql.fallback_compiler; see Configuration Reference): if you install only one knowledge compiler, install that one so the fallback step in the default-strategy chain has something to invoke.

Each tool must be installed as an executable reachable in the PATH of the PostgreSQL server process (e.g., /usr/local/bin/). If the tools live outside that PATH (a Conda environment, $HOME/local/bin, /opt/...), point ProvSQL at them with the provsql.tool_search_path GUC; see Configuration Reference.
(Optional) graph-easy for circuit visualisation (libgraph-easy-perl on Debian-based systems, or CPAN). Same PATH considerations as above apply.

Installation

Compile:
```
make
```
To select a specific PostgreSQL installation, adjust the pg_config path in Makefile.internal.
Install (as a user with write access to the PostgreSQL directories):
```
make install
```
Enable the extension hook. Add the following line to postgresql.conf (typically /etc/postgresql/VERSION/main/postgresql.conf on Linux):
```
shared_preload_libraries = 'provsql'
```
Then restart the PostgreSQL server:
```
service postgresql restart
```
Important

The shared_preload_libraries step is mandatory. ProvSQL installs a planner hook that rewrites queries transparently; without it the extension loads but provenance tracking is silently disabled.
In each database where you want to use ProvSQL, load the extension:
```
CREATE EXTENSION provsql CASCADE;
```
The CASCADE keyword automatically installs the required uuid-ossp extension if it is not already present.
Make sure provsql is in your search_path. ProvSQL’s operators and functions live in the provsql schema and are resolved through search_path (see Schema and search_path for what goes wrong without it). CREATE EXTENSION prints a NOTICE if it is missing; the easiest fix is the bundled helper:
```
SELECT provsql.setup_search_path();
```
which appends provsql to the database’s search_path (only new sessions are affected). See Schema and search_path for the manual alternative and the details.

Upgrading an Existing Installation

Starting with 1.2.1, ProvSQL ships PostgreSQL extension upgrade scripts covering every released version from 1.0.0 onwards (see sql/upgrades/ in the source tree for the exact chain available in your checkout). To upgrade an existing installation:

Check out the new source, build, and install (as a user with write access to the PostgreSQL directories):
```
make
make install
```
If you are upgrading across 1.3.0 (i.e. from any pre-1.3.0 release), migrate the on-disk provenance store before restarting PostgreSQL. 1.3.0 changed the memory-mapped layout from a flat $PGDATA/provsql_*.mmap set to per-database files under $PGDATA/base/<db_oid>/ with a versioned header. Build and run the bundled migration tool as the postgres system user with the server stopped (adjust the connection string for your socket directory if different):
```
make provsql_migrate_mmap
sudo -u postgres ./provsql_migrate_mmap -D $PGDATA -c "host=/var/run/postgresql"
```
The tool removes the old flat files on success. Skip this step when upgrading between 1.3.0+ releases.
Restart PostgreSQL so the new shared library is loaded:
```
service postgresql restart
```
In each database where provsql is already installed, issue:
```
ALTER EXTENSION provsql UPDATE;
```
PostgreSQL will find the chain of upgrade scripts between your current version and the newly installed one and apply them in order, inside a single transaction. The persistent provenance circuit (stored in memory-mapped files) is preserved across the upgrade.

Note

Upgrades from pre-1.0.0 development snapshots are not supported: no upgrade script is provided and you must DROP EXTENSION provsql CASCADE; CREATE EXTENSION provsql instead. Any provenance tokens previously stored in user tables become orphans and will not be resolvable against the new circuit store.

Note

In-place ALTER EXTENSION provsql UPDATE is not supported on PostgreSQL < 12 when crossing the 1.4.0 → 1.5.0 boundary: the 1.5.0 release introduces new gate-type enum values via several ALTER TYPE ... ADD VALUE statements, and PostgreSQL 10 and 11 reject more than one such statement inside the single transaction PostgreSQL wraps the upgrade chain in. Fresh installs (CREATE EXTENSION provsql) work on every supported PostgreSQL version; the restriction only affects the in-place upgrade path across that one boundary. To move a pre-1.5.0 database forward under PostgreSQL 10 or 11, upgrade to PostgreSQL 12+ first (the provenance store carries over unchanged) and then run ALTER EXTENSION provsql UPDATE.

Testing Your Installation

Run the full regression suite as a PostgreSQL superuser:

make test

If tests fail, the pager (usually less) is launched on the diff between expected and actual output.

Note

To run the tests as a non-default user, grant yourself superuser rights first:

ALTER USER your_login WITH SUPERUSER;

This assumes your_login is already a PostgreSQL user; on Debian-based systems you can create it by running createuser your_login as the postgres system user.

If your PostgreSQL server does not listen on the default port (5432), add --port=xxxx to the EXTRA_REGRESS_OPTS line of Makefile.internal.

Tests that depend on optional external tools (c2d, d4, dsharp, minic2d, weightmc, graph-easy) are automatically skipped if the tool is not found in $PATH.

Uninstalling

make uninstall

Then remove the provsql entry from shared_preload_libraries in postgresql.conf and restart the server.

Via PGXN

ProvSQL is distributed on the PostgreSQL Extension Network. If you have the pgxnclient tool installed, a single command (run as a user with write access to the PostgreSQL directories) downloads, builds, and installs the extension:

pgxn install provsql

You still need the build prerequisites (C++17 compiler, Boost headers, PostgreSQL server development headers, and a working pg_config on your PATH) and you still need to add provsql to shared_preload_libraries in postgresql.conf and restart the server afterwards – pgxn install wraps the source build but does not modify your server configuration.

To install a specific version:

pgxn install provsql=X.Y.Z

Docker Container

For a quick trial without any local installation, a demonstration Docker container is available. Alongside the extension and a pre-installed ProvSQL Studio it bundles a set of the optional external tools: the d4 and dsharp knowledge compilers, the ganak, sharpsat-td and weightmc weighted model counters, and graph-easy for ASCII circuit rendering.

docker run -p 5433:5432 -p 8001:8000 inriavalda/provsql

The -p host:container flags publish the container’s PostgreSQL (5432) and ProvSQL Studio (8000) on host ports of your choice, which works uniformly across native Docker, Docker Desktop, and rootless podman. The example maps them to 5433 and 8001 to avoid clashing with a PostgreSQL or Studio you may already run locally on the default 5432 / 8000; pick whatever free host ports you like. To use a specific release version:

docker run -p 5433:5432 -p 8001:8000 inriavalda/provsql:X.Y.Z

Connect with a PostgreSQL client (psql -h localhost -p 5433 tutorial test) or open Studio at http://localhost:8001 (matching the host ports you chose); the container also prints these instructions on startup.

The image is seeded with the same tutorial and case-study databases as the ProvSQL Playground (tutorial, cs1, cs2, cs4–cs7). Studio lands on tutorial; switch between them from its connection chip, or point psql at any of them (e.g. psql -h localhost -p 5433 cs1 test).

ProvSQL Studio

ProvSQL Studio is a Python-backed web UI for ProvSQL, distributed as a separate package on PyPI. It connects to any ProvSQL-enabled database and provides interactive provenance inspection (Where mode), circuit visualisation (Circuit mode), and on-the-fly semiring evaluation. See ProvSQL Studio for installation and usage.

License

ProvSQL is open-source software distributed under the MIT License. See the LICENSE file at the root of the repository or view it on GitHub.