CLIOperatorPlan before apply

Treat PostgreSQL access like a control plane, not a pile of grants.

Define roles, memberships, schema profiles, and default privileges once. Review the exact SQL plan, then let pgroles converge the database and keep drift visible.

Start with a diffExplore the operator
Convergent model
Manifest is truth
Preview path
CLI diff + operator plan
Runtime
CI, OTLP, Kubernetes

Desired state

Policy manifest

profiles:
  writer:
    grants:
      - privileges: [USAGE]
        on: { type: schema }
      - privileges: [SELECT, INSERT, UPDATE, DELETE, TRIGGER]
        on: { type: table, name: "*" }
      - privileges: [USAGE, SELECT, UPDATE]
        on: { type: sequence, name: "*" }

Change plan

Diff summary

Plan: 4 change(s)
  1 role(s) to create
  2 grant(s) to add
  1 default privilege(s) to set

Control plane

Operator status

status:
  conditions:
    - type: Ready
      status: "True"
      reason: Planned
    - type: Drifted
      status: "True"

Introduction

Getting started

One YAML file. Every role, grant, and privilege in your database — defined, diffed, and applied.

Why pgroles?

Managing PostgreSQL roles and privileges across environments is error-prone. Teams typically resort to ad-hoc SQL scripts, manual GRANT statements, or fragile migration files. When a new schema is added or a role needs adjusting, it's easy to miss a grant or leave stale privileges in place.

pgroles takes a convergent, declarative approach: you define the desired state in a YAML manifest, and pgroles computes the exact SQL needed to bring your database in line. Anything in the database but not in the manifest gets revoked or dropped — so your access control never drifts.

Built for platform teams, DBAs, and anyone managing more than a handful of PostgreSQL roles across environments.

Key features

  • Write privilege rules once, expand them across every schema automatically via profiles
  • See exactly what will change before touching the database with pgroles diff
  • Convergent diff engine — the manifest is the entire truth; stale grants get revoked
  • Dry-run mode to preview generated SQL without executing
  • Default privilege management so future tables get the right grants automatically
  • Role membership management with inherit and admin flags
  • Safe drops — preflight checks block dropping roles with owned objects or active sessions
Start here

Quick start

Install pgroles and run your first diff against a live database.

Open guide
Schema

Manifest format

Learn the full YAML manifest schema for defining roles and privileges.

Open guide
Patterns

Profiles & schemas

Use profiles to define reusable privilege templates across schemas.

Open guide
Reference

CLI reference

All available commands: validate, diff, apply, and inspect.

Open guide
Next
Quick start