Cluster
Clusters are a core primitive that represent a hosted Crunchy Bridge Postgres database along with all associated resources required to operate it, including the cloud server that it runs on.
Clusters are named such because the internal replica needed to maintain a cluster with high availability is considered to be part of same cluster as its primary, thereby making it a “cluster” of multiple servers. Public-facing replicas and forks on the other hand, are represented in the API as separate clusters with their own uniquely addressable IDs.
See also upgrading clusters to change a cluster’s disk size, high availability configuration, or Postgres major version.
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 Cluster
API resource
A database cluster.
Content type: application/json
Name | Nullable | Type | Description |
---|---|---|---|
id | string in EID format |
The unique ID of the cluster. |
|
cluster_id | âś” | string in EID format |
In the case of a replica, the ID of the primary cluster. Always |
cpu | integer |
The number of CPU units on the cluster’s instance. |
|
created_at | string of date/time formatted as RFC 3339 |
Time at which the cluster was originally created. |
|
disk_usage | object of type ClusterDiskUsage |
Contains information on the cluster’s current disk usage. This data is collected about once a day, and isn’t guaranteed to be perfectly fresh. For a new cluster, it may also not have been collected yet at all, in which case this field will be |
|
is_ha | boolean |
Whether the cluster is high availability, meaning that it has a secondary it can fail over to quickly in case the primary becomes unavailable. |
|
is_protected | boolean |
Whether the cluster is protected. Protected clusters can’t be destroyed until their protected flag is removed (which can be done via the “update cluster” endpoint). |
|
is_suspended | boolean |
Indicates whether the cluster is currently in a suspended state, meaning that while its disk is available, it doesn’t currently have a running virtual machine. |
|
maintenance_Âwindow_Âstart | âś” | integer |
The hour of day which a maintenance window can possibly start. This should be an integer from |
major_version | integer |
The cluster’s major Postgres version. For example, |
|
memory | integer |
The total amount of memory available on the cluster’s instance in GB (gigabytes). |
|
name | string |
A human-readable name for the cluster. |
|
network_id | âś” | string in EID format |
The ID of the network where the cluster is located. |
plan_id | string |
The ID of the cluster’s plan. Determines instance, CPU, and memory. |
|
postgres_Âversion_Âid | string in EID format |
The ID of the cluster’s major Postgres version. |
|
provider_id | string |
The cloud provider where the cluster is located. |
|
region_id | string |
The provider region where the cluster is located. |
|
replicas | array of object of type Cluster |
Replicas for the cluster. Always empty for a non-primary cluster. |
|
storage | integer |
The amount of storage available to the cluster in GB (gigabytes). |
|
team_id | string in EID format |
The ID of the team that the cluster belongs to. |
|
updated_at | string of date/time formatted as RFC 3339 |
Time at which the cluster was last updated. |
Example
{
"cluster_id": null,
"cpu": 16,
"created_at": "2021-07-11T01:02:03Z",
"disk_usage": {
"disk_available_mb": 95000,
"disk_total_size_mb": 100000,
"disk_used_mb": 5000
},
"id": "rvf73a77ozfsvcttryebfrnlem",
"is_ha": false,
"is_protected": false,
"is_suspended": false,
"maintenance_window_start": 21,
"major_version": 13,
"memory": 64,
"name": "crunchy-production",
"network_id": "p56biajnfvgjhftvqs7lqymspe",
"plan_id": "standard-64",
"postgres_version_id": "6ibnzig5avgutdgdzei2jwvvt4",
"provider_id": "aws",
"region_id": "us-west-2",
"replicas": [
{
"cluster_id": null,
"cpu": 16,
"created_at": "2021-07-11T01:02:03Z",
"disk_usage": null,
"id": "drsve2t4f5e5znkmef6hmchy2e",
"is_ha": false,
"is_protected": false,
"is_suspended": false,
"maintenance_window_start": null,
"major_version": 13,
"memory": 64,
"name": "crunchy-production-replica",
"network_id": "p56biajnfvgjhftvqs7lqymspe",
"plan_id": "standard-64",
"postgres_version_id": "6ibnzig5avgutdgdzei2jwvvt4",
"provider_id": "aws",
"region_id": "us-west-2",
"replicas": null,
"storage": 100,
"team_id": "eaevtjiudzeq7bsqbbpiscund4",
"updated_at": "2021-07-11T01:02:03Z"
}
],
"storage": 100,
"team_id": "eaevtjiudzeq7bsqbbpiscund4",
"updated_at": "2021-07-11T01:02:03Z"
}
The ClusterDiskUsage
object
Contains information about a cluster's disk usage.
Name | Nullable | Type | Description |
---|---|---|---|
disk_available_mb | integer |
Available disk left in MB (megabytes). |
|
disk_Âtotal_Âsize_Âmb | integer |
Total disk size in MB (megabytes). |
|
disk_used_mb | integer |
Amount of disk currently in use in MB (megabytes). |
List clusters
List clusters for a specific team.
This endpoint’s pagination may be ordered through the order_field
parameter
by id
or name
. Defaults to being ordered by name
.
GET /clusters
Request
Query parameters
Name | Required | Type | Description |
---|---|---|---|
cursor | string |
Return only items starting after this cursor ID. When paginating, pass the value of |
|
limit | integer |
The maximum number of items to return on the page. Defaults to |
|
order | enum string |
The order of pagination. Enum |
|
order_field | string |
The name of the field on which to paginate like |
|
team_id | string |
ID of the team for which to list clusters. If not provided then this value defaults to the ID of the requesting user. |
cURL example
curl -X GET https://api.crunchybridge.com/clusters
-H "Authorization: Bearer $CRUNCHY_API_KEY"
Response
Status: 200
Response for listing clusters.
Content type: application/json
Name | Nullable | Type | Description |
---|---|---|---|
clusters | array of object of type Cluster |
List of clusters for this page. |
|
has_more | boolean |
Indicates whether or not there are more resources to page through in the collection. |
|
next_cursor | âś” | string in EID format |
A cursor value to pass to the endpoint to get the next page. |
Example
{
"clusters": [
{
"cluster_id": null,
"cpu": 16,
"created_at": "2021-07-11T01:02:03Z",
"disk_usage": {
"disk_available_mb": 95000,
"disk_total_size_mb": 100000,
"disk_used_mb": 5000
},
"id": "rvf73a77ozfsvcttryebfrnlem",
"is_ha": false,
"is_protected": false,
"is_suspended": false,
"maintenance_window_start": 21,
"major_version": 13,
"memory": 64,
"name": "crunchy-production",
"network_id": "p56biajnfvgjhftvqs7lqymspe",
"plan_id": "standard-64",
"postgres_version_id": "6ibnzig5avgutdgdzei2jwvvt4",
"provider_id": "aws",
"region_id": "us-west-2",
"replicas": [
{
"cluster_id": null,
"cpu": 16,
"created_at": "2021-07-11T01:02:03Z",
"disk_usage": null,
"id": "drsve2t4f5e5znkmef6hmchy2e",
"is_ha": false,
"is_protected": false,
"is_suspended": false,
"maintenance_window_start": null,
"major_version": 13,
"memory": 64,
"name": "crunchy-production-replica",
"network_id": "p56biajnfvgjhftvqs7lqymspe",
"plan_id": "standard-64",
"postgres_version_id": "6ibnzig5avgutdgdzei2jwvvt4",
"provider_id": "aws",
"region_id": "us-west-2",
"replicas": null,
"storage": 100,
"team_id": "eaevtjiudzeq7bsqbbpiscund4",
"updated_at": "2021-07-11T01:02:03Z"
}
],
"storage": 100,
"team_id": "eaevtjiudzeq7bsqbbpiscund4",
"updated_at": "2021-07-11T01:02:03Z"
}
],
"has_more": false,
"next_cursor": null
}
Create cluster
Create a database cluster.
POST /clusters
Request
Request body schema
Content type: application/json
Name | Required | Type | Description |
---|---|---|---|
name | âś” | string |
A human-readable name for the cluster. |
plan_id | âś” | string |
The ID of the plan with which to create the cluster. Determines instance, CPU, and memory. |
provider_id | âś” | string |
The cloud provider in which to create the cluster. |
region_id | âś” | string |
The provider region in which to create the cluster. |
team_id | âś” | string in EID format |
The ID of the team that the cluster should belong to. Admin privilege on the team is required. |
is_ha | boolean |
Whether the cluster should be high availability, meaning that it has a secondary it can fail over to quickly in case the primary becomes unavailable. |
|
network_id | string in EID format |
The ID of the network where the new cluster should be created. The cluster is created in its own new network if left empty. |
|
postgres_Âversion_Âid | integer , or string |
An identifier for the Postgres version to create the cluster with. May be either the primary ID of a Postgres version or a major version number like Defaults to Postgres 14. |
|
storage | integer |
The amount of storage to make available to the cluster in GB (gigabytes). |
|
major_version | integer |
The major Postgres version with which to create the cluster. Deprecated Prefer sending a value to |
Example request body
{
"name": "crunchy-production",
"plan_id": "hobby-2",
"postgres_version_id": 13,
"provider_id": "aws",
"region_id": "us-west-2",
"storage": 100,
"team_id": "eaevtjiudzeq7bsqbbpiscund4"
}
cURL example
curl -X POST https://api.crunchybridge.com/clusters
-H "Authorization: Bearer $CRUNCHY_API_KEY"
-H "Content-Type: application/json"
-d '{"name":"crunchy-production","plan_id":"hobby-2","postgres_version_id":13,"provider_id":"aws","region_id":"us-west-2","storage":100,"team_id":"eaevtjiudzeq7bsqbbpiscund4"}'
Response
Status: 201
Responds with the standard Cluster
API resource.
Get cluster
Get a cluster by ID.
GET /clusters/{cluster_id}
Request
Path parameters
- cluster_id: The ID of the cluster to retrieve.
cURL example
curl -X GET https://api.crunchybridge.com/clusters/{cluster_id}
-H "Authorization: Bearer $CRUNCHY_API_KEY"
Response
Status: 200
Responds with the standard Cluster
API resource.
Update cluster
Update various properties of an existing cluster.
PATCH /clusters/{cluster_id}
Request
Path parameters
- cluster_id: The ID of the cluster to update.
Request body schema
Content type: application/json
Name | Required | Type | Description |
---|---|---|---|
is_protected | boolean |
Make the cluster protected, which means that it can’t be destroyed until it’s explicitly set as unprotected. |
|
maintenance_Âwindow_Âstart | integer |
The desired hour of day which a maintenance window can possibly start. This should be an integer from Send |
|
name | string |
Name is the new human-readable name to be assigned to the cluster. |
Example request body
{
"maintenance_window_start": 3,
"name": "new-cluster-name"
}
cURL example
curl -X PATCH https://api.crunchybridge.com/clusters/{cluster_id}
-H "Authorization: Bearer $CRUNCHY_API_KEY"
-H "Content-Type: application/json"
-d '{"maintenance_window_start":3,"name":"new-cluster-name"}'
Response
Status: 200
Responds with the standard Cluster
API resource.
Destroy cluster
Delete a database cluster.
DELETE /clusters/{cluster_id}
Request
Path parameters
- cluster_id: The ID of the cluster to delete.
cURL example
curl -X DELETE https://api.crunchybridge.com/clusters/{cluster_id}
-H "Authorization: Bearer $CRUNCHY_API_KEY"
Response
Status: 200
Responds with the standard Cluster
API resource.
Get cluster status
Gets the online status for a cluster. This differs from the standard get endpoint in that it contains information that’s retrieved directly from the cluster itself, rather than information about the cluster that’s stored out of band and which may not be as current.
GET /clusters/{cluster_id}/status
Request
Path parameters
- cluster_id: The ID of the cluster to get status for.
cURL example
curl -X GET https://api.crunchybridge.com/clusters/{cluster_id}/status
-H "Authorization: Bearer $CRUNCHY_API_KEY"
Response
Status: 200
Response for getting a cluster’s online status.
Content type: application/json
Name | Nullable | Type | Description |
---|---|---|---|
disk_usage | object of type ClusterDiskUsage |
Contains information on the cluster’s current disk usage. |
|
oldest_backup_at | âś” | string of date/time formatted as RFC 3339 |
The cluster’s oldest backup. May be null if no backup has occurred yet. |
ongoing_upgrade | object of type ClusterUpgrade |
Information on an ongoing upgrade in the cluster (like if it’s major version is being changed or its disk is being resized). Null if there is no upgrade ongoing. |
|
state | enum string |
The state of the cluster. Enum |
Example
{
"disk_available_mb": 0,
"disk_total_size_mb": 0,
"disk_usage": {
"disk_available_mb": 94948,
"disk_total_size_mb": 100213,
"disk_used_mb": 133
},
"disk_used_mb": 0,
"oldest_backup_at": "2021-07-11T01:02:03Z",
"ongoing_upgrade": {
"operations": [
{
"flavor": "ha_change",
"state": "waiting_for_ha_standby"
},
{
"flavor": "resize",
"state": "in_progress"
}
]
},
"state": "ready"
}
The ClusterUpgrade
object
Response for the status of a cluster upgrade.
Name | Nullable | Type | Description |
---|---|---|---|
operations | array of object of type ClusterUpgradeOperation |
Contains ongoing upgrade operations. Empty if there are no ongoing upgrade operations. |
Example
{
"operations": [
{
"flavor": "ha_change",
"state": "waiting_for_ha_standby"
},
{
"flavor": "resize",
"state": "in_progress"
}
]
}
The ClusterUpgradeOperation
object
An ongoing upgrade operation (like a version upgrade or resize) within a database cluster.
Name | Nullable | Type | Description |
---|---|---|---|
flavor | âś” | enum string |
The kind of upgrade. Enum |
state | âś” | enum string |
The state of the ongoing resize. One of One of Enum |
Create cluster fork
Create a fork of an existing database cluster.
Note that target_time
must be between the cluster’s oldest backup (see
oldest_backup_at
under cluster status) and the
current time. Clusters can’t be forked until an initial backup has been
captured for them. This will occur shortly after they’re created, but a brand
new cluster may not be available for forking right away.
POST /clusters/{cluster_id}/forks
Request
Path parameters
- cluster_id: The ID of the cluster to fork.
Request body schema
Content type: application/json
Name | Required | Type | Description |
---|---|---|---|
name | âś” | string |
A human-readable name for the fork. |
plan_id | âś” | string |
The ID of the plan with which to create the fork. Determines instance, CPU, and memory. |
provider_id | âś” | string |
The cloud provider in which to create the fork. |
region_id | âś” | string |
The provider region in which to create the fork. |
is_ha | boolean |
Whether the fork should be high availability, meaning that it has a secondary it can fail over to quickly in case the primary becomes unavailable. |
|
network_id | string in EID format |
The ID of the network where the new fork should be created. The cluster is created in its own new network if left empty. |
|
storage | integer |
The amount of storage to make available to the fork in GB (gigabytes). |
|
target_time | string of date/time formatted as RFC 3339 |
The time at which to fork from. Leave empty to fork at the current time. If specified, must be between the cluster’s oldest backup (see |
Example request body
{
"name": "crunchy-production-fork",
"plan_id": "standard-64",
"provider_id": "aws",
"region_id": "us-west-2",
"storage": 100,
"target_time": "2021-07-11T01:02:03Z"
}
cURL example
curl -X POST https://api.crunchybridge.com/clusters/{cluster_id}/forks
-H "Authorization: Bearer $CRUNCHY_API_KEY"
-H "Content-Type: application/json"
-d '{"name":"crunchy-production-fork","plan_id":"standard-64","provider_id":"aws","region_id":"us-west-2","storage":100,"target_time":"2021-07-11T01:02:03Z"}'
Response
Status: 201
Responds with the standard Cluster
API resource.
Restart cluster
Restart the underlying server of a cluster, or a specific service on it.
The restart occurs asynchronously and calling this endpoint multiple times will idempotently queue up a only single restart until that restart occurs, at which point a new restart can be queued.
PUT /clusters/{cluster_id}/actions/restart
Request
Path parameters
- cluster_id: The ID of the cluster.
Request body schema
Content type: application/json
Name | Required | Type | Description |
---|---|---|---|
service | enum string |
Service is the target service on the cluster to restart. Defaults to Enum |
cURL example
curl -X PUT https://api.crunchybridge.com/clusters/{cluster_id}/actions/restart
-H "Authorization: Bearer $CRUNCHY_API_KEY"
Response
Status: 200
Responds with the standard Cluster
API resource.
Suspend cluster
Suspends a cluster, which deactivates the virtual machine it’s running on but keeps its disk image around so that it can later be resumed. Normal billing for the cluster is suspended, but storage costs will continue to accrue.
Currently this feature is only supported on AWS and Azure, and the target cluster must be a primary.
PUT /clusters/{cluster_id}/actions/suspend
Request
Path parameters
- cluster_id:
cURL example
curl -X PUT https://api.crunchybridge.com/clusters/{cluster_id}/actions/suspend
-H "Authorization: Bearer $CRUNCHY_API_KEY"
Response
Status: 200
Responds with the standard Cluster
API resource.
Resume cluster
Resumes normal operation of a suspended cluster. Normal billing is resumed as well.
PUT /clusters/{cluster_id}/actions/resume
Request
Path parameters
- cluster_id:
cURL example
curl -X PUT https://api.crunchybridge.com/clusters/{cluster_id}/actions/resume
-H "Authorization: Bearer $CRUNCHY_API_KEY"
Response
Status: 200
Responds with the standard Cluster
API resource.
Start backup
Request to start a new backup capture on a cluster.
Backups occur asynchronously, and will be visible from the list backups endpoint when completed. A request to this endpoint might be a no-op in case a backup is already in progress, or a backup was requested recently.
Existing backups are available via the list backups endpoint.
PUT /clusters/{cluster_id}/actions/start-backup
Request
Path parameters
- cluster_id:
cURL example
curl -X PUT https://api.crunchybridge.com/clusters/{cluster_id}/actions/start-backup
-H "Authorization: Bearer $CRUNCHY_API_KEY"
Response
Status: 200
A simple message response.
These responses tend to come from endpoints that affect some kind of change but do not return the target API resource. e.g. creating a backup, etc.
Content type: application/json
Name | Nullable | Type | Description |
---|---|---|---|
message | string |
The message of the response. |
Example
{
"message": "Server will restart momentarily."
}