Installation

Prerequisites

Requirement	Version	Notes
PostgreSQL	14, 15, 16, or 17	WAL sync mode is roadmap work
Rust	1.78+ (stable)	For building from source
cargo-pgrx	Latest	`cargo install cargo-pgrx --version 0.18.0 --locked`
OS	Linux (x86_64, aarch64), macOS	Windows not supported

Install from Source

1. Install Rust and pgrx


# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
 
# Install cargo-pgrx
cargo install cargo-pgrx --version 0.18.0 --locked
 
# Initialize pgrx with your PostgreSQL installation
cargo pgrx init --pg17=$(which pg_config)
# Adjust for your version: --pg14, --pg15, --pg16

2. Clone and Build


git clone https://github.com/Evokoa/pggraph.git
cd pggraph/graph
 
# Build and install into your PostgreSQL installation
cargo pgrx install --release
 
# Or build a distributable package
cargo pgrx package --pg-config=$(which pg_config)

3. Enable the Extension


-- Connect to your database
psql -d your_database
 
-- Create the extension
CREATE EXTENSION graph;
 
-- Verify
SELECT * FROM graph.status();

Install from Package (Future)

For production deployments, pre-built packages will be available:


# Debian/Ubuntu (future)
sudo apt-get install postgresql-17-graph
 
# PGXN (future)
pgxn install graph
 
# Docker (future)
docker run -d postgres:17-graph

Configuration

Essential Settings

Add to postgresql.conf or use ALTER SYSTEM:


# Load the extension on startup for GUC registration and page-cache prewarm.
shared_preload_libraries = 'graph'
 
# Core settings
graph.enabled = on
graph.sync_mode = 'trigger'       # V1 supports 'manual' and 'trigger'; 'wal' is roadmap
graph.auto_load = on       # Load graph into RAM on server start

All GUC Parameters

Parameter	Type	Default	Reload?	Description
`graph.enabled`	bool	`on`	Yes	Master kill switch
`graph.data_dir`	string	`graph`	No	Subdirectory of `$PGDATA`
`graph.memory_limit_mb`	int	`2048`	No	Hard memory limit (ERROR, not crash)
`graph.sync_mode`	enum	`trigger`	No	`manual`, `trigger`; `wal` is roadmap
`graph.vacuum_interval_secs`	int	`60`	Yes	Auto-vacuum period
`graph.edge_buffer_size`	int	`100000`	No	Max pending edge mutations
`graph.auto_load`	bool	`on`	No	Preload graph on startup
`graph.default_max_depth`	int	`5`	Yes	Default BFS depth
`graph.max_nodes`	int	`100000`	Yes	Default circuit breaker
`graph.max_frontier`	int	`100000`	Yes	Default frontier limit
`graph.max_token_length`	int	`128`	No	Max property length for TokenIndex
`graph.bloom_bits`	int	`64`	No	Bloom signature width
`graph.bloom_hash_count`	int	`1`	No	Hash functions per token
`graph.oom_action`	enum	`error`	Yes	`error` or `readonly`

“Reload?” = Can be changed with SELECT pg_reload_conf() (no restart needed) vs. requires Postgres restart.

Quick Start Script

The scripted quickstart in bench/verification/timed_quickstart.sh times a local proof-of-concept flow after PostgreSQL, Rust, cargo-pgrx, and the extension build prerequisites already exist. It is not evidence for client-site deployment time.


# 1. Build and install
cargo pgrx install --release
 
# 2. Restart Postgres (needed for shared_preload_libraries)
pg_ctl restart -D $PGDATA
 
# 3. Create extension + auto-discover your schema
psql -d mydb -c "CREATE EXTENSION graph; SELECT * FROM graph.auto_discover();"
# Build/register the graph before querying production schemas.
 
# 4. Query!
psql -d mydb -c "SELECT * FROM graph.traverse('customers', '1', 3);"

Manual Setup (If You Want Control)


psql -d mydb <<'SQL'
CREATE EXTENSION graph;
 
SELECT graph.add_table('customers', id_columns := ARRAY['id'],
    columns := ARRAY['name', 'email', 'status']);
SELECT graph.add_table('orders', id_columns := ARRAY['id'],
    columns := ARRAY['status', 'total']);
 
SELECT graph.add_edge('orders', 'customer_id', 'customers', 'id', 'customer');
 
SELECT graph.build();
SQL

Upgrading

Minor Version Upgrade (e.g., 0.1.0 → 0.1.1)


ALTER EXTENSION graph UPDATE TO '0.1.1';

Major Version Upgrade (e.g., 0.1.x → 0.2.0)


# 1. Build new version
cargo pgrx install --release
 
# 2. Restart Postgres
pg_ctl restart -D $PGDATA
 
# 3. Upgrade extension
psql -d mydb -c "ALTER EXTENSION graph UPDATE TO '0.2.0';"
 
# 4. Rebuild graph (new version may change .graph format)
psql -d mydb -c "SELECT graph.build();"

Uninstalling


-- Remove the extension (drops all functions, triggers, catalog tables)
DROP EXTENSION graph CASCADE;


# Remove persisted graph files
rm -rf $PGDATA/graph/
 
# Remove from shared_preload_libraries in postgresql.conf
# Then restart Postgres

Troubleshooting

Extension won’t load


ERROR: could not access file "graph": No such file or directory

→ The shared library wasn’t installed. Run cargo pgrx install --release again.

”wal sync is roadmap/future work”


ERROR: graph.sync_mode = 'wal' is roadmap/future work; use 'trigger' or 'manual' for V1

→ Use graph.sync_mode = 'trigger' for V1 automatic sync, or manual for batch snapshots.

Out of memory during build


ERROR: graph: memory limit exceeded (using 2048 MB, need 512 MB more, limit is 2048 MB)
HINT: Increase graph.memory_limit_mb or reduce the number of registered tables.

→ Increase graph.memory_limit_mb and ensure your machine has sufficient RAM. See Memory Model for capacity planning.

Slow first query after restart

The first query after a restart may take longer due to mmap page faults warming the cache. Set graph.auto_load = on to pre-warm on startup.

Trigger not firing

Ensure graph.sync_mode = 'trigger' and that you’ve run graph.build() (which installs triggers). Check with:


SELECT tgname, tgrelid::regclass
FROM pg_trigger
WHERE tgname LIKE 'graph_%';