Cluster role

Get and manage roles within a database cluster. In Postgres, the term "role" and "user" are largely synonymous.

On Bridge, new instances start with two roles by default:

  • application: A non-superuser, suitable for use in application code.

  • postgres: A superuser, capable of performing any action in a database.

Credentials for both roles can be requested through the API, but an account will need admin privilege on a cluster's team to request the postgres role.

The API previously supported another role called default, which was also a superuser role. default is being phased out in favor of postgres and considered deprecated -- use postgres instead.

In accordance with the principle of least privilege, we recommend the postgres superuser role be used sparingly -- only where necessary to perform administrative operations where a superuser is needed. Application code should use the application user, which has all the permissions necessary for such, but without as much ability to perform database-wide changes that could potentially be catastrophic.

Additionally, the API allows the creation of other roles for specific accounts, which may be useful for auditing purposes as not every database user is sharing a single Postgres role. When creating this sort of extra role, it requires a specific name format of u_<account_id>. For example, u_qvcw4hylovgyzbwzp53bmmlhga.

The update role endpoint is idempotent, meaning that it can be used to create or update a role without having to first check whether that role already exists. This can make writing application code that raises roles automatically easier to write and more robust.

Note that although Bridge provides an API for creating roles, it doesn't mandate its use. It's still possible to use a superuser to run CREATE ROLE SQL via a normal database connection.

Part of the API reference collection

This page is part of the Crunchy Bridge API reference, and primarily meant to act as an exhaustive guide for technical integrations which are already in progress. To understand the basics of using the API, see API concepts and getting started.

The ClusterRole API resource

Response of a singleton cluster role request.

Content type: application/json

NameNullableTypeDescription
account_email✔string

The email of the account the role belongs to.

This field is only set when the role name is tied to an account and has a prefix or u_. Otherwise it is set to null.

account_id✔string in EID format

The ID of the account the role belongs to.

This field is only set when the role name is tied to an account and has a prefix or u_. Otherwise it is set to null.

cluster_idstring in EID format

The ID of cluster that the role belongs to.

flavor✔enum string

The type of role assigned to the role. A write role has CRUD privileges while read is read-only.

Enum read, or write.

namestring

Name of the role in Postgres.

Either application, postgres, or a role name tied to an account ID with a prefix of u_. For example, u_qvcw4hylovgyzbwzp53bmmlhga.

password✔string

Password of the role in Postgres.

Redacted to null when the role is rendered to event data or from the role list or destroy endpoints.

team_idstring in EID format

The ID of the team that owns the associated cluster.

uri✔string

A full URI that can be used as a Postgres connection string for the role.

Redacted to null when the role is rendered to event data or from the role list or destroy endpoints.

Example

{
    "account_email": null,
    "account_id": null,
    "cluster_id": "rvf73a77ozfsvcttryebfrnlem",
    "flavor": "write",
    "name": "application",
    "password": "Yodtp6pRYzUsqNeHFIDVS3ViS266l5WeifCkdsvdzosQ1jTBMvKJKYF7h0tuMHd7",
    "team_id": "eaevtjiudzeq7bsqbbpiscund4",
    "uri": "postgres://postgres:Yodtp6pRYzUsqNeHFIDVS3ViS266l5WeifCkdsvdzosQ1jTBMvKJKYF7h0tuMHd7@p.33ddusyv3fgkrf2bz67bxlkpwa.db.postgresbridge.com:5432/postgres"
}

List roles

List existing roles for a cluster.

This endpoint's pagination may be ordered through the order_field parameter by id or name. Defaults to being ordered by id.

GET /clusters/{cluster_id}/roles

Request

Path parameters

  • cluster_id: Unique ID of the cluster.

Query parameters

NameRequiredTypeDescription
account_idarray

Account ID or set of account IDs to filter the list response to. This is useful for performing bulk role lookup by account ID.

cursorstring

Return only items starting after this cursor ID. When paginating, pass the value of next_cursor from the last page into this field to get the next one.

Cursor values depend on the field in order_field. Cursors will often be the primary IDs of object, but when ordering on another field like name, they'll be names (or another value) instead.

limitinteger

The maximum number of items to return on the page. Defaults to 100 with a minimum of 1 and a maximum of 200.

orderstring

The order of pagination. asc for ascending or desc for descending. Defaults to asc.

Enum asc, or desc.

order_fieldstring

The name of the field on which to paginate like id or name. Supported fields are specific to each endpoint, and it's not possible to specify any arbitrary name. See the documentation for each specific list endpoint to see which fields it supports. Defaults to id for most resources.

cURL example

curl -X GET https://api.crunchybridge.com/clusters/{cluster_id}/roles
    -H "Authorization: Bearer $CRUNCHY_API_KEY"

Response

Status: 200

Response for listing cluster roles.

Content type: application/json

NameNullableTypeDescription
rolesarray of array

List of roles for cluster.

Create role

Create a new role in a cluster.

POST /clusters/{cluster_id}/roles

Request

Path parameters

  • cluster_id: Unique ID of the cluster.

cURL example

curl -X POST https://api.crunchybridge.com/clusters/{cluster_id}/roles
    -H "Authorization: Bearer $CRUNCHY_API_KEY"

Response

Status: 201

Responds with the standard ClusterRole API resource.

Get role

Get an existing role for a cluster.

GET /clusters/{cluster_id}/roles/{role_name}

Request

Path parameters

  • cluster_id: Unique ID of the cluster.
  • role_name: Unique name of the role to be retrieved.

cURL example

curl -X GET https://api.crunchybridge.com/clusters/{cluster_id}/roles/{role_name}
    -H "Authorization: Bearer $CRUNCHY_API_KEY"

Response

Status: 200

Responds with the standard ClusterRole API resource.

Update role

Idempotently updates or creates (if it didn't exist) a role in a cluster.

PUT /clusters/{cluster_id}/roles/{role_name}

Request

Path parameters

  • cluster_id: Unique ID of the cluster.

  • role_name: Unique name of the role to be created or updated.

    Valid values are application, postgres, user or an account role name like u_<account_id> eg. u_qvcw4hylovgyzbwzp53bmmlhga.

Request body schema

Content type: application/json

NameRequiredTypeDescription
flavorenum string

The type of role to assign the role. If no flavor is provided, the flavor of the role is not updated. A write role has CRUD privileges while read is read-only.

Enum read, or write.

rotate_passwordboolean

Specifies whether to change the role's password to a generated value. If false, the role's password is not changed.

Example request body

{
    "flavor": null,
    "rotate_password": null
}

cURL example

curl -X PUT https://api.crunchybridge.com/clusters/{cluster_id}/roles/{role_name}
    -H "Authorization: Bearer $CRUNCHY_API_KEY"
    -H "Content-Type: application/json"
    -d '{"flavor":null,"rotate_password":null}'

Response

Status: 201

Responds with the standard ClusterRole API resource.

Delete role

Delete an existing role for a cluster.

DELETE /clusters/{cluster_id}/roles/{role_name}

Request

Path parameters

  • cluster_id: Unique ID of the cluster.
  • role_name: Unique name of the role to be deleted.

cURL example

curl -X DELETE https://api.crunchybridge.com/clusters/{cluster_id}/roles/{role_name}
    -H "Authorization: Bearer $CRUNCHY_API_KEY"

Response

Status: 200

Responds with the standard ClusterRole API resource.