Quick start - pgroles docs

Get up and running with pgroles in a few minutes.

Prerequisites

PostgreSQL 14+ (pgroles adapts membership SQL to the server version at runtime)
PostgreSQL 16+ recommended for full per-membership INHERIT support
CI coverage currently runs integration tests on PostgreSQL 16, 17, and 18
Rust toolchain (for building from source)

Installation

Build from source using Cargo:

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

This installs the pgroles binary.

Starting from an existing database?

Use pgroles generate --database-url ... > pgroles.yaml first, then refine the generated flat manifest into profiles and schema bindings.

Create a manifest

Create a file called pgroles.yaml:

default_owner: app_owner

roles:
  - name: analytics
    login: true
    comment: "Analytics read-only role"

grants:
  - role: analytics
    privileges: [CONNECT]
    on: { type: database, name: mydb }
  - role: analytics
    privileges: [USAGE]
    on: { type: schema, name: public }
  - role: analytics
    privileges: [SELECT]
    on: { type: table, schema: public, name: "*" }

Validate the manifest

Check the manifest is valid without connecting to a database:

pgroles validate

Manifest is valid.
  1 role(s) defined
  3 grant(s) defined
  0 default privilege(s) defined
  0 membership(s) defined

Plan changes

See what SQL would be generated against a live database:

pgroles diff --database-url postgres://localhost/mydb

This shows the exact SQL statements needed to converge the database to match your manifest.

No changes are made

The diff command (also available as plan) is read-only. It connects to your database to inspect the current state but does not execute any changes.

Apply changes

When you're happy with the plan, apply it:

pgroles apply --database-url postgres://localhost/mydb

Or preview without executing:

pgroles apply --database-url postgres://localhost/mydb --dry-run

Using environment variables

Instead of passing --database-url every time, set the DATABASE_URL environment variable:

export DATABASE_URL=postgres://localhost/mydb
pgroles diff
pgroles apply