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

Name	Nullable	Type	Description
`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_id`		`string` 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`.
`name`		`string`	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_id`		`string` 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

Name	Type	Description
`cursor`	`string`	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.
`limit`	`integer`	The maximum number of items to return on the page. Defaults to `100` with a minimum of `1` and a maximum of `100`.
`order`	`string`	The order of pagination. `asc` for ascending or `desc` for descending. Defaults to `asc`. Enum `asc`, or `desc`.
`order_field`	`string`	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

Name	Nullable	Type	Description
`roles`		`array` 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.

application or postgres can be specified here and although those roles already exist by default, their credentials will be returned. Otherwise, a newly created role must conform to the format of an account ID with u_ prefix. For example, u_qvcw4hylovgyzbwzp53bmmlhga.

Request body schema

Content type: application/json

Name Required Type Description

Name	Required	Type	Description
`flavor`		enum `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_password`		`boolean`	Specifies whether to change the role's password to a generated value. If false, the role's password is not changed.

flavor

enum 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_password

boolean

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.