listRoles

Return cluster-wide roles with kind (login/group), attributes (superuser, create_role, create_db, replication, bypass_rls, connection_limit, valid_until), and group memberships.

read-onlyany connectionsweeps group

Synopsis

listRoles([pattern])

Description

Return cluster-wide roles with kind (login/group), attributes (superuser, create_role, create_db, replication, bypass_rls, connection_limit, valid_until), and group memberships. Without 'pattern' the list is capped at 200, ordered so every role carrying a non-default attribute or a group membership comes first -- on a multi-tenant cluster with one login role per tenant the crowd is identical and the cap drops it rather than the superusers.

Pass 'pattern' to search by name (case-insensitive substring) when the role you want is outside the cap.

Parameters

pattern optionalstring: case-insensitive substring of the role name

Also accepts connection, group, described once under arguments every tool takes.

Output

Keyed by role name; each value is its attributes and group memberships. An absent extension or a missing grant is reported as {error, hint} in place of the map.

Scope

This reading is instance-wide -- every database on the same postmaster returns it identically, so asking each of them in turn repeats one answer. A physical replica is byte-identical here, so asking each member of a replication group adds nothing.

Example mocked data

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "listRoles",
    "arguments": {
      "pattern": "app"
    }
  }
}

Result

{
  "app_rw": {
    "kind": "login",
    "description": "Application read-write role.",
    "superuser": false,
    "inherit": true,
    "create_role": false,
    "create_db": false,
    "replication": false,
    "bypass_rls": false,
    "connection_limit": 200,
    "valid_until": null,
    "member_of": [
      "app_base"
    ]
  }
}

Invented values on a fictional shop database, shaped by and checked against this tool's output schema. Real output is returned as structuredContent to clients that negotiate MCP 2025-06-18 or later.