Planning and reconciliation modes
On this page
Preview the changes against your database before choosing what to apply.
Preview a policy
With DATABASE_URL set for the target database, validate the policy and inspect an additive plan:
pgroles validate -f pgroles.yaml
pgroles diff -f pgroles.yaml --mode additive
Validation checks the policy without inspecting a database. diff connects to the target and plans changes without applying them. Check executor privileges when inspection or preflight reports a failure.
Choose a reconciliation mode
| Mode | Review focus |
|---|---|
additive | Add declared access while retaining existing access; revocations and drops are skipped. Start here when adopting an existing database. |
adopt | Reconcile declared roles, including removals, while retaining undeclared roles. Review revoked grants and memberships carefully. |
authoritative | Also allow eligible role drops within the managed scope. Review retirement operations and dependencies. |
These modes control the permitted effects, not whether the executor can perform them. See staged adoption for a rollout sequence and the mode reference for exact behaviour and ownership-transfer guards.
Share the review
Export a recorded review to share the native plan without giving a reviewer database access. Use the explorer for browser-local policy authoring and hypothetical comparisons, and the CI/CD guide for automated drift checks.
Operator execution has separate observe/apply and approval gates. Follow plan and approval or candidates and promotion for those workflows. A native review fingerprint does not approve an operator plan.