Packaging

User-facing install instructions are in the install guide. This page collects the details packagers and platform teams ask about.

Platform

• PostgreSQL 18 only.
• Linux on x86-64 or arm64 with glibc 2.39 or newer: the official postgres:18 image, Debian 13, or Ubuntu 24.04 and later. musl-based systems such as Alpine are not supported.
• The release binaries are built inside a Debian trixie container against PostgreSQL 18 and validated on postgres:18-trixie. The glibc floor is measured from the shipped .so and recorded in the tarball's MANIFEST.json.

What gets installed

File	Destination
lib/pgrdf.so	$(pg_config --pkglibdir), or any directory on dynamic_library_path
share/extension/pgrdf.control	$(pg_config --sharedir)/extension, or any directory on extension_control_path
share/extension/pgrdf--<version>.sql	beside the control file (the install script)
share/extension/pgrdf--<from>--<to>.sql	beside the control file (upgrade scripts)

pgRDF depends on no other extension.

Release tarball layout

pgrdf-<ver>-pg18-glibc-<arch>/
├── lib/pgrdf.so
├── share/extension/pgrdf.control
├── share/extension/pgrdf--<ver>.sql
├── share/extension/pgrdf--<from>--<to>.sql   (every upgrade script)
├── LICENSE
├── MANIFEST.json
└── SHA256SUMS

SHA256SUMS inside the tarball covers every file in it, including MANIFEST.json. MANIFEST.json records the version, extversion, the runtime pgrdf.version() value, the install and upgrade script names, the platform (PostgreSQL major, architecture, base image, build image, measured glibc floor) and the build (tag, commit, date). It is generated from the repacked files, so it cannot disagree with what shipped. The same tarball is published as an attested OCI artifact; see Release.

Control file

The shipped pgrdf.control:

Setting	Value	Consequence
default_version	the release version	what CREATE EXTENSION pgrdf installs
module_pathname	'pgrdf'	a bare name, so PostgreSQL searches dynamic_library_path; a $libdir/ prefix would bypass it
schema	pgrdf	objects are created in the pgrdf schema
relocatable	false	the schema cannot be changed after install
superuser	true	CREATE EXTENSION needs a superuser
trusted	false	non-superusers cannot install it

After installation, an application role needs ordinary privileges on the pgrdf schema, its tables and sequences (and CREATE on the schema to call add_graph, which creates a partition). The install guide lists the grants.

Required server setting

shared_preload_libraries = 'pgrdf'

Preloading lets _PG_init run in the postmaster and reserve shared memory for the term cache, the cross-backend counters and the staged loader's job-control segment. Without it the extension installs and most functions work, but the shared term cache and the staged loader are unavailable, and pgrdf.stats()->'shmem_ready' is false. See Architecture.

Directory-based install

PostgreSQL 18 can load extensions from directories outside the installation, which suits read-only images and Kubernetes volumes:

postgres -c shared_preload_libraries=pgrdf \
         -c 'extension_control_path=/opt/pgrdf/share:$system' \
         -c 'dynamic_library_path=/opt/pgrdf/lib:$libdir'

In Kubernetes, an init container can unpack the release tarball into an emptyDir mounted at /opt/pgrdf, and the PostgreSQL container starts with the three settings above. The postgres image itself needs no modification.

Upgrades

Upgrade scripts (sql/pgrdf--<from>--<to>.sql in the repository) ship in every release from 0.6.22 onward. To upgrade:

1. install the new files;
2. restart the server, so the new library is loaded (a preloaded library is only read at start-up);
3. run ALTER EXTENSION pgrdf UPDATE in each database.

Stored graphs are kept. An upgrade script adds new functions and applies any schema change, such as new columns on _pgrdf_graphs.

Replacing pgrdf.so while the server is running is unsafe: backends have the old file mapped. Stop the server, swap the files, then start it again.

Backups

_pgrdf_graphs and _pgrdf_dictionary are registered with pg_extension_config_dump, so pg_dump includes their rows. The round trip is tested by tests/regression/scripts/pg-dump-roundtrip.sh and pg-dump-dict-roundtrip.sh. For a portable copy of one graph that can be verified offline, use export_graph and graph_manifest; see Identity and export.

Verifying an installation

SELECT pgrdf.version(), pgrdf.build_id(),
       (SELECT extversion FROM pg_extension WHERE extname = 'pgrdf');
--  0.6.34 | v0.6.34 | 0.6.34

• version() is the version the library was compiled as.
• build_id() identifies the build. A release build reports its tag; a local build reports git describe output such as v0.6.34-2-gab92a33-dirty; unknown means no id was supplied.
• extversion is the installed SQL version; it matches version() once ALTER EXTENSION … UPDATE has run.

All three agreeing means the running library is the release you installed. The regression suite checks the same values in 00-smoke.sql.