pgroles-policy

Pgroles Policy

Use the pgroles version installed by the project. Read its matching documentation or checked-out source before using fields introduced in newer releases.

Choose The Source Of Truth

Use pgroles for steady-state roles, memberships, grants, schema ownership, and default privileges. Keep provider identities and cloud login plumbing in the cloud/IaC system. Use migrations for ordered object changes that desired-state reconciliation cannot infer, such as reassigning existing object ownership or creating SECURITY DEFINER functions.

Do not manage the same role attribute, membership, or grant in two systems after the migration window ends.

Authoring Workflow

1. Identify the database, PostgreSQL version, executor identity, and installed pgroles version.
2. Inspect nearby manifests and the actual database. For brownfield adoption, start with pgroles generate; use --suggest-profiles only after reviewing that the refactoring preserves the exact expanded state.
3. Define reusable profiles by access shape, then bind them to schemas. Profiles create concrete roles using role_pattern: schema override, then policy default, then {schema}-{profile}. Bundles resolve schema → fragment → shared.role_pattern → built-in default. Every declared pattern requires {profile}. Review naming changes as role changes, not cosmetic edits.
4. Declare managed roles and memberships explicitly. Use external: true for a role whose lifecycle belongs to a provider or another system.
5. Model current and future objects separately: ordinary grants cover existing objects; default privileges cover only future objects created by the named owner.
6. Validate, inspect the expanded graph, and review the SQL diff before apply.

Useful commands:

pgroles validate -f pgroles.yaml
pgroles graph desired -f pgroles.yaml
pgroles diff -f pgroles.yaml --database-url "$DATABASE_URL"

Use pgroles diff --format markdown for a review artifact and retain stderr warnings. Bundle changes are attributed to their owning source document. The redacted report fingerprint identifies that report, not database state or an execution approval; it excludes password values and database identity. Record the target environment alongside it. Markdown records declared password changes without reading their environment variables. Review the SQL and effective privileges as well as the conservative change priorities.