Skip to content
pg_warrenbyExaDev

Installation

pg_warren supports PostgreSQL 15, 16, 17 and 18 (16 is the development baseline). CREATE EXTENSION pg_warren does not need a superuser (below). Packages are published from 0.7.0 on; for an earlier release, build from source.

Debian 12 and 13, Ubuntu 22.04 and 24.04 (amd64, arm64): a signed apt repository of postgresql-NN-pg-warren packages, built against PGDG’s PostgreSQL, whose postgresql-NN they depend on (add PGDG first unless your distribution ships that major). Add the key and the source once:

Terminal window
sudo install -d /etc/apt/keyrings
curl -fsSL https://exadev.github.io/pg_warren/apt/pg_warren.asc \
  | sudo tee /etc/apt/keyrings/pg_warren.asc >/dev/null
echo "deb [signed-by=/etc/apt/keyrings/pg_warren.asc] https://exadev.github.io/pg_warren/apt $(. /etc/os-release && echo "$VERSION_CODENAME") main" \
  | sudo tee /etc/apt/sources.list.d/pg_warren.list
sudo apt update
sudo apt install postgresql-17-pg-warren   # or -15, -16, -18

Check the key before trusting it: gpg --show-keys /etc/apt/keyrings/pg_warren.asc must show the fingerprint A7FF D766 EE91 5EE8 E970 85F8 DF33 D764 5F72 1A34 , which every GitHub Release’s notes repeat.

The package does not edit postgresql.conf. Add the preload yourself (below: on PG 15 and 16 it is what lets backends share loaded graphs) and restart: shared_preload_libraries = 'pg_warren' in /etc/postgresql/17/main/postgresql.conf, then sudo systemctl restart postgresql@17-main.

Docker, the quickest way to try it: PGDG’s official postgres image (Debian 13) with the package installed and pg_warren preloaded, for amd64 and arm64:

Terminal window
docker run --rm --shm-size=1g -e POSTGRES_PASSWORD=postgres -p 5432:5432 ghcr.io/exadev/pg_warren:pg17

Tags are pgNN (the latest release) and X.Y.Z-pgNN. --shm-size sizes the container’s /dev/shm, where the shared cache keeps loaded graphs (below); Docker’s default is 64 MB. 1g shares graphs of up to about 750 MB; for the default cap of 4GB, give it 6g. docker/Dockerfile builds an image from source instead (docker build -f docker/Dockerfile --build-arg PG_MAJOR=17 -t pg_warren:pg17 .).

macOS (Homebrew), for Homebrew’s postgresql@17 and postgresql@18; a bottle on Apple silicon, built from source (with Rust) on Intel:

Terminal window
brew install exadev/tap/pg_warren

Then add shared_preload_libraries = 'pg_warren' to $(brew --prefix)/var/postgresql@18/postgresql.conf and brew services restart postgresql@18 (brew info pg_warren repeats this). macOS is not yet a supported platform: CI runs the tests there without gating on them, and the shared cache, which measures /dev/shm (absent on macOS), is expected to keep a copy per backend (DESIGN.md §13, M11). Postgres.app is not supported for now.

Other Linux (glibc 2.35 or later): each GitHub Release has pg_warren-X.Y.Z-pgNN-linux-{x86_64,aarch64}.tar.gz, built on Ubuntu 22.04. Copy its files where that PostgreSQL’s pg_config says (its INSTALL says the same), then preload and restart as above:

Terminal window
cp pkglibdir/* "$(pg_config --pkglibdir)"
cp sharedir/extension/* "$(pg_config --sharedir)/extension"

RPM packages (RHEL, Fedora) and PGXN are planned, not built yet.

Managed PostgreSQL (Amazon RDS and Aurora, Cloud SQL, Azure, Supabase, Neon and the like) installs only the extensions the provider ships, so pg_warren cannot be installed there until a provider adopts it. You can run it on a server of your own beside the managed database, fed by logical replication: docs/beside-managed.md.

From source, with Rust (the toolchain pinned in rust-toolchain.toml), the server headers (postgresql-server-dev-NN), clang/libclang-dev, and cargo-pgrx at exactly the version the extension uses:

Terminal window
git clone https://github.com/ExaDev/pg_warren.git
cd pg_warren
git checkout v0.8.0   # the latest release; main is the version in development
cargo install cargo-pgrx --version 0.19.3 --locked
cargo pgrx init --pg16 "$(command -v pg_config)"
cd crates/pg_warren
cargo pgrx install --release --pg-config "$(command -v pg_config)"

To build without network access (each release’s pg_warren-X.Y.Z-vendored.tar.gz carries every crate), or reproducibly, or to verify a release’s signed SHA256SUMS, its SBOM and its source, see CONTRIBUTING.md, “Supply chain”.

Then, in each database:

CREATE EXTENSION pg_warren;
SELECT warren.version();

pg_warren is a trusted extension, so this does not need a superuser: any role with CREATE on the database can run it, as on hosted Postgres. That role becomes the extension’s owner. It may update the extension (ALTER EXTENSION pg_warren UPDATE) or drop it, which drops every graph in the database. It gets no direct access to the warren.* tables, which belong to the bootstrap superuser. Every role, the installer included, reaches graphs only through the warren.* functions and their access checks (DESIGN.md §7).

On PG 15+ the database owner also owns schema public. A graph’s source queries run as the graph’s owner, under the search_path it was created with. If that path includes a schema another role can create in, such as public when someone else owns the database, that role could add a function or operator that the queries then call as the graph’s owner at every refresh. Schema-qualify the functions and operators in source queries, or create graphs under a search_path of schemas only their owner can write; create_graph raises a NOTICE when it finds such a schema.

Graphs, versions and vectors are ordinary tables, so pg_dump includes them, and a plain (psql) or custom (pg_restore) restore brings them back. The roles that own and read graphs must exist first. pg_dump warns about circular foreign-key constraints on warren.versions (it references itself) and suggests --disable-triggers: ignore that hint, which would skip pg_warren’s catalog checks, and restore normally. Without a superuser, dump as a role granted pg_read_all_data and restore as one granted pg_write_all_data (on Amazon RDS from PG 15, the master user has both); other non-superusers cannot read or write the catalog, so their pg_dump fails while pg_warren is installed. Those two roles reach every graph directly, so grant them only for the dump or the restore (docs/security.md, “Dumps and restores”).

The shared cache. A loaded graph version is kept once per cluster, in dynamic shared memory, and mapped by every backend that reads it, so pooled connections share one copy instead of loading one each. It is on by default (warren.shared_cache_memory = 4GB, cluster-wide). On PostgreSQL 17 and 18 it needs nothing configured. On 15 and 16 it needs pg_warren preloaded (a restart):

shared_preload_libraries = 'pg_warren'

Without that, or where /dev/shm is too small, each backend loads its own copy, as before 0.5.0, rather than fail. Sizing, containers and the other settings are in docs/limits.md.

Upgrading from an earlier release: install the new build, then run ALTER EXTENSION pg_warren UPDATE; in every database that has the extension, before calling any warren.* function. The new library is loaded at once, but the catalog changes only with the update, so calls in between can fail.