Installation

Compatibility

• PostgreSQL 16+: Full support including GRANT ... WITH INHERIT/WITH ADMIN syntax
• PostgreSQL 14–15: Supported with automatic fallback to legacy grant syntax (WITH ADMIN OPTION)
• CI integration tests run against PostgreSQL 16, 17, and 18
• pgroles detects the server version at runtime and adapts SQL generation accordingly

From source

pgroles is written in Rust. Build and install with Cargo:

cargo install --git https://github.com/hardbyte/pgroles pgroles-cli

This compiles the pgroles binary and places it in your Cargo bin directory (usually ~/.cargo/bin/).

From crates.io

cargo install pgroles-cli

From a local clone

git clone https://github.com/hardbyte/pgroles.git pgroles
cd pgroles
cargo build --release

The binary will be at target/release/pgroles.

From GitHub Releases

Download pre-built binaries from the releases page.

Docker

docker run --rm ghcr.io/hardbyte/pgroles --help

Published container images are multi-arch for linux/amd64 and linux/arm64. The release workflow builds the Linux binaries first and then assembles the runtime images from those artifacts, so published images do not recompile Rust inside the Docker publish jobs.

Local Docker validation

To reproduce the live CLI tests against a local PostgreSQL:

docker run --rm --name pgroles-pg16 \
  -e POSTGRES_PASSWORD=testpassword \
  -e POSTGRES_DB=pgroles_test \
  -p 5432:5432 \
  postgres:16

In another shell:

export DATABASE_URL=postgres://postgres:testpassword@localhost:5432/pgroles_test
cargo test -p pgroles-cli --test cli live_db::diff_against_live_db -- --ignored --exact
cargo test -p pgroles-cli --test cli live_db::diff_summary_format -- --ignored --exact

Use postgres:17 or postgres:18 to mirror the CI matrix.

Contributor notes

• docker/Dockerfile is the source-build path used for local builds and E2E-style flows.
• docker/Dockerfile.runtime is the release assembly path used in GitHub Actions.
• BuildKit cache mounts are used in docker/Dockerfile for Cargo registry, git, and target caches.
• The release workflow does not need Cargo cache mounts in the Docker step because it consumes prebuilt Linux binaries from the earlier build job.

Verify installation

pgroles --version
pgroles --help