Grants & privileges

Grants define what privileges a role has on database objects. pgroles supports granting on specific objects, all objects of a type in a schema, schemas themselves, and databases.

Grant syntax

grants:
  - role: analytics
    privileges: [SELECT]
    object:
      type: table
      schema: public
      name: "*"

The preferred key is object. pgroles still accepts a quoted legacy "on" key when parsing older manifests, but new manifests should use object to avoid YAML 1.1 boolean coercion.

Privilege types

Grant targets

Schema-level

Grant privileges on the schema itself (e.g. USAGE to allow accessing objects within it):

grants:
  - role: analytics
    privileges: [USAGE]
    object: { type: schema, name: public }

Generates: GRANT USAGE ON SCHEMA "public" TO "analytics";

Database-level

grants:
  - role: analytics
    privileges: [CONNECT]
    object: { type: database, name: mydb }

Generates: GRANT CONNECT ON DATABASE "mydb" TO "analytics";

Wildcard (all objects of a type in schema)

Use name: "*" to grant on all existing objects of a type:

grants:
  - role: analytics
    privileges: [SELECT]
    object: { type: table, schema: public, name: "*" }

pgroles expands wildcard relation grants against the current objects of the requested type in that schema. That keeps table, view, and materialized_view grants scoped correctly instead of letting one subtype touch the others.

If a schema has no objects of the declared type (e.g. no sequences yet), the wildcard grant is treated as vacuously satisfied — pgroles will not re-issue the statement on subsequent reconciles. When objects are later added, the next reconcile detects the new objects and applies the appropriate grants.

Specific object

grants:
  - role: analytics
    privileges: [SELECT]
    object: { type: table, schema: public, name: users }

Generates: GRANT SELECT ON TABLE "public"."users" TO "analytics";

Privilege merging

If multiple grant entries target the same role and object, their privileges are merged:

grants:
  - role: app
    privileges: [SELECT]
    object: { type: table, schema: public, name: "*" }
  - role: app
    privileges: [INSERT, UPDATE]
    object: { type: table, schema: public, name: "*" }

This is equivalent to granting SELECT, INSERT, UPDATE on all tables.

Convergent revocation

Privileges present in the database but absent from the manifest are revoked. If a role currently has DELETE on a table but your manifest only grants SELECT, pgroles will generate a REVOKE DELETE statement.