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 |
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 |
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 Enum |
name | string | Name of the role in Postgres. Either | |
password | ✔ | string | Password of the role in Postgres. Redacted to |
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 |
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 | Required | Type | Description |
---|---|---|---|
cursor | string | Return only items starting after this cursor ID. When paginating, pass the value of Cursor values depend on the field in | |
limit | integer | The maximum number of items to return on the page. Defaults to | |
order | string | The order of pagination. Enum | |
order_field | string | The name of the field on which to paginate like |
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.Valid values are
application
,postgres
,user
or an account role name likeu_<account_id>
eg.u_qvcw4hylovgyzbwzp53bmmlhga
.
Request body schema
Content type: application/json
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 Enum | |
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.