Get Started with Pgrust on macOS and Linux

Pgrust ships as a pre-built binary that replaces the standard postgres server executable. Because it is 100% wire-compatible with PostgreSQL 18.3, you use the existing PostgreSQL client tools — initdb, psql, and any Postgres driver — to initialize, manage, and query it. The steps below get you from zero to a running server in under five minutes.

Prefer containers? See the Docker guide to run Pgrust with a single docker run command — no client tools required.

Install and Run

macOS (Apple Silicon)
Linux (Debian / Ubuntu)

Install PostgreSQL 18 client tools

Pgrust reuses the standard PostgreSQL initdb and psql utilities. Install them via Homebrew. Because postgresql@18 is a keg-only formula, Homebrew does not put its binaries on your PATH automatically - you must export the path yourself:

brew install postgresql@18
export PATH="$(brew --prefix postgresql@18)/bin:$PATH"

You do not need to start the Homebrew-managed PostgreSQL service. Only the client tools are required.

Download the Pgrust binary

Download the latest pre-built binary and verify its checksum. Using curl (rather than a browser download) avoids macOS Gatekeeper quarantine flags:

curl -LO https://pgrust.com/downloads/v0.2/pgrust-0.2-macos-arm64
curl -LO https://pgrust.com/downloads/v0.2/pgrust-0.2-macos-arm64.sha256
shasum -a 256 -c pgrust-0.2-macos-arm64.sha256
chmod +x pgrust-0.2-macos-arm64

macOS Gatekeeper: the binaries are not yet Apple-notarized. If you download with a browser instead of curl, macOS may block execution. Clear the quarantine flag with:

xattr -d com.apple.quarantine pgrust-0.2-macos-arm64

Or approve the binary under System Settings → Privacy & Security → Open Anyway.

Intel Mac: use pgrust-0.2-macos-x86_64 in place of pgrust-0.2-macos-arm64. A universal binary (pgrust-0.2-macos-universal) covering both architectures is also available.

Set required environment variables

Pgrust reads PostgreSQL’s shared data files (timezone data, error messages, etc.) at runtime. Without these two variables it looks in /usr/local/pgsql/share and refuses to start:

export PGRUST_PGSHAREDIR="$(brew --prefix postgresql@18)/share/postgresql"
export PGRUST_TZDIR="$PGRUST_PGSHAREDIR/timezone"

Add these lines (and the PATH export from Step 1) to your shell profile (~/.zshrc or ~/.bash_profile) so they are set automatically in every new session.

Initialize a data directory

Use the standard initdb tool to create and initialize a PostgreSQL data directory:

initdb -D /tmp/pgrust-data --no-locale --encoding UTF8 -U postgres

Start the Pgrust server

Start the server in the foreground. The ulimit and RUST_MIN_STACK settings prevent stack overflows on deep query plans:

ulimit -s 65520
RUST_MIN_STACK=33554432 ./pgrust-0.2-macos-arm64 \
  -D /tmp/pgrust-data \
  -k /tmp -p 5432 \
  -c listen_addresses= \
  -c io_method=sync \
  -c max_stack_depth=60000

You should see startup log output similar to a standard PostgreSQL server. The server listens on the Unix socket /tmp/.s.PGSQL.5432.

Connect with psql and run a test query

Open a second terminal. Re-export the PATH if you haven’t added it to your profile, then connect via the Unix socket:

export PATH="$(brew --prefix postgresql@18)/bin:$PATH"
psql -h /tmp -p 5432 -U postgres -c "select version()"

You should see pgrust 0.2 (PostgreSQL 18.3 compatible).

Install PostgreSQL 18 client tools

Install initdb and psql from the official PostgreSQL Global Development Group (PGDG) APT repository. On Debian and Ubuntu, initdb ships in the postgresql-18 server package and is not placed on PATH by default — export it manually:

sudo apt-get update
sudo apt-get install -y curl ca-certificates gnupg
sudo install -d /usr/share/postgresql-common/pgdg
sudo curl -fsSL -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc \
  https://www.postgresql.org/media/keys/ACCC4CF8.asc
echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] \
  http://apt.postgresql.org/pub/repos/apt $(. /etc/os-release && echo $VERSION_CODENAME)-pgdg main" \
  | sudo tee /etc/apt/sources.list.d/pgdg.list
sudo apt-get update
sudo apt-get install -y postgresql-18 postgresql-client-18
export PATH="/usr/lib/postgresql/18/bin:$PATH"

Download the Pgrust binary

Set your platform and download the binary with checksum verification:

PLATFORM=linux-x86_64    # or: linux-aarch64

curl -LO "https://pgrust.com/downloads/v0.2/pgrust-0.2-$PLATFORM"
curl -LO "https://pgrust.com/downloads/v0.2/pgrust-0.2-$PLATFORM.sha256"
sha256sum -c "pgrust-0.2-$PLATFORM.sha256"
chmod +x "pgrust-0.2-$PLATFORM"

Set required environment variables

Pgrust reads PostgreSQL’s shared data files at runtime. On Debian/Ubuntu, Postgres is built against the system tzdata, so PGRUST_TZDIR points to the system zoneinfo directory:

export PGRUST_PGSHAREDIR=/usr/share/postgresql/18
export PGRUST_TZDIR=/usr/share/zoneinfo

Add these lines and the PATH export to ~/.bashrc or /etc/environment so they persist across sessions and reboots.

Initialize a data directory

Use initdb to create and initialize a data directory:

initdb -D /tmp/pgrust-data --no-locale --encoding UTF8 -U postgres

Start the Pgrust server

Start the server in the foreground:

ulimit -s 65520
RUST_MIN_STACK=33554432 "./pgrust-0.2-$PLATFORM" \
  -D /tmp/pgrust-data \
  -k /tmp -p 5432 \
  -c listen_addresses= \
  -c io_method=sync \
  -c max_stack_depth=60000

The server listens on the Unix socket /tmp/.s.PGSQL.5432.

Connect with psql and run a test query

Open a second terminal and connect:

psql -h /tmp -p 5432 -U postgres -c "select version()"

You should see pgrust 0.2 (PostgreSQL 18.3 compatible).

Managing the Server

Stop with Ctrl-C in the server terminal, or kill -INT <pid>. This triggers PostgreSQL’s fast shutdown and is safe.
Restart by re-running the same server command against the same data directory. Your data is preserved across restarts.
Start over by deleting the data directory: rm -rf /tmp/pgrust-data. This permanently deletes all data in it.

Troubleshooting

FATAL: lock file "/tmp/.s.PGSQL.5432.lock" already exists — another server (likely an existing Postgres install) is already using port 5432. Start Pgrust on a different port:

# add -p 5433 to the server command, then connect with:
psql -h /tmp -p 5433 -U postgres -c "select version()"

After connecting, always run SELECT version() to confirm you are talking to Pgrust and not a background Postgres instance.

could not open directory "/usr/local/pgsql/share/timezone" — the PGRUST_PGSHAREDIR and PGRUST_TZDIR environment variables are not set in the shell running the server. Re-export them before starting.

Using Other PostgreSQL Clients

Because Pgrust is 100% wire-compatible with PostgreSQL 18.3, any standard PostgreSQL client or driver works without modification:

GUI tools: pgAdmin, TablePlus, DBeaver, DataGrip
Language drivers: libpq, psycopg2 / psycopg3 (Python), node-postgres / pg (Node.js), pgx / lib/pq (Go), diesel / sqlx (Rust), JDBC (Java)
ORMs: SQLAlchemy, Prisma, ActiveRecord, Hibernate, GORM

Use the standard PostgreSQL connection string format:

postgresql://username:password@localhost:5432/dbname

No special drivers, extensions, or configuration changes are needed on the client side.

Advanced: stdio-wire Transport

The postgres binary exposes a --stdio-wire flag that routes the PostgreSQL wire protocol over stdin/stdout instead of a network socket. This is an advanced transport used internally for the WebAssembly browser demo and differential testing. You do not need it for normal local or networked usage.

Building from Source

If you prefer to compile Pgrust yourself, or are targeting a platform without a pre-built binary, you can build from source. Rust 1.96.0 is pinned via rust-toolchain.toml and fetched automatically by rustup — you do not need to install a specific version manually.

Install build dependencies

Pgrust depends on Google’s RE2 regular expression library. Release builds refuse to compile without it on purpose — a build using only the fallback regex engine is drastically slower on regex-heavy workloads.

brew install re2 pkg-config

sudo apt-get install -y build-essential pkg-config libre2-dev

Clone the repository and build

git clone https://github.com/malisper/pgrust.git
cd pgrust

cargo build --release --locked --bin postgres

The compiled binary lands at target/release/postgres. A cold build on a modern laptop typically takes 5–10 minutes.

The published downloadable binaries are built with --profile dist, which enables fat LTO for a faster binary at the cost of a much longer compile time. For local development, --release is sufficient.

Run the binary

Follow the same environment variable, initdb, and startup steps from the platform tabs above, substituting target/release/postgres as the binary path.

​Install and Run

​Managing the Server

​Troubleshooting

​Using Other PostgreSQL Clients

​Advanced: stdio-wire Transport

​Building from Source

Install and Run

Managing the Server

Troubleshooting

Using Other PostgreSQL Clients

Advanced: stdio-wire Transport

Building from Source