Cluster replica
Create and manage cluster replicas.
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_group | object of type ClusterGroup object | The cluster group that the cluster belongs to, if any. | |
cluster_id | ✔ | string in EID format | In the case of a replica, the ID of the primary cluster. Always Deprecate: Prefer use of |
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 object | 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 | |
environment | ✔ | enum string | The type of environment which the cluster belongs to. This is largely for informational purposes, but may affect the cluster's display and interaction from Bridge tools. For example, a value of Enum |
host | string | The hostname of the cluster. | |
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. | |
keychain_id | ✔ | string in EID format | The ID of the keychain used by the cluster for encrypting its data. |
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 | number | The total amount of memory available on the cluster's instance in GB (gigabytes). This is normally a whole integer, but may be fractional for the case of smaller hobby instances that have less than a gigabyte of memory. | |
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. |
parent_id | ✔ | string in EID format | The ID of the primary or parent cluster or a replica cluster. Always |
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 | ✔ | enum string | The cloud provider where the cluster is located. Enum |
region_id | string | The provider region where the cluster is located. | |
replicas | array of array | Replicas for the cluster. | |
reset_stats_weekly | boolean | Whether | |
storage | integer | The amount of storage available to the cluster in GB (gigabytes). | |
tailscale_active | boolean | Indicates whether tailscale is active for the cluster. | |
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",
"dashboard_settings": {
"heroku_database_id": null,
"heroku_migration_complete": null
},
"disk_usage": {
"disk_available_mb": 95000,
"disk_total_size_mb": 100000,
"disk_used_mb": 5000
},
"environment": null,
"host": "p.rvf73a77ozfsvcttryebfrnlem.crunchybridge.com",
"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",
"parent_id": null,
"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",
"dashboard_settings": null,
"disk_usage": null,
"environment": null,
"host": "",
"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",
"parent_id": null,
"plan_id": "standard-64",
"postgres_version_id": "6ibnzig5avgutdgdzei2jwvvt4",
"provider_id": "aws",
"region_id": "us-west-2",
"replicas": null,
"reset_stats_weekly": true,
"storage": 100,
"tailscale_active": false,
"team_id": "eaevtjiudzeq7bsqbbpiscund4",
"updated_at": "2021-07-11T01:02:03Z"
}
],
"reset_stats_weekly": true,
"storage": 100,
"tailscale_active": false,
"team_id": "eaevtjiudzeq7bsqbbpiscund4",
"updated_at": "2021-07-11T01:02:03Z"
}
The ClusterGroup
object
A cluster group, which is often a Citus cluster.
Name | Nullable | Type | Description |
---|---|---|---|
id | string in EID format | Unique ID of the cluster group. | |
clusters | array of array | Clusters in the group. This field is omitted when the cluster group is being rendered as a subresource of another API resource like a cluster. | |
kind | enum string | The kind of cluster group. Enum | |
name | string | A human-friendly name of the cluster group. | |
network_id | string in EID format | ID of the network on which the cluster group is located. | |
provider_id | ✔ | enum string | ID of the provider on which the cluster group is located. Enum |
region_id | string | ID of the region where the cluster group is located. | |
team_id | string in EID format | ID of the team which the cluster group belongs to. |
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). |
Create cluster replica
Create a read-replica for an existing database cluster.
POST /clusters/{cluster_id}/replicas
Request
Path parameters
cluster_id
: The ID of the cluster to create a replica for.
Request body schema
Content type: application/json
Name | Required | Type | Description |
---|---|---|---|
name | ✔ | string | A human-readable name for the replica. |
cluster_group_id | string in EID format | The ID of the cluster group that the replica should be assigned to. | |
keychain_id | string in EID format | The ID of the keychain that should be used by the replica for encrypting its data. | |
network_id | string in EID format | The ID of the network where the new replica should be created. If left empty, then the cluster is created in the same network as its primary or a new network if the replica is to be created in a different region from the primary. If specified, both | |
plan_id | string | The ID of the plan with which to create the replica. Determines instance, CPU, and memory. If not specified, defaults to the primary cluster's plan. | |
provider_id | enum string | The cloud provider in which to create the replica. If not specified, defaults to the primary cluster's provider. If specified then If specified, then Enum | |
region_id | string | The provider region in which to create the replica. If not specified, defaults to the primary cluster's region. If set, then either If specified, then |
Example request body
{
"cluster_group_id": null,
"keychain_id": null,
"name": "crunchy-production-replica",
"plan_id": "standard-64"
}
cURL example
curl -X POST https://api.crunchybridge.com/clusters/{cluster_id}/replicas
-H "Authorization: Bearer $CRUNCHY_API_KEY"
-H "Content-Type: application/json"
-d '{"cluster_group_id":null,"keychain_id":null,"name":"crunchy-production-replica","plan_id":"standard-64"}'
Response
Status: 201
Responds with the standard Cluster
API resource.
Detach replica
Detach a replica from its primary.
The replica detaches asynchronously and calling this endpoint multiple times before the final detach resolves will no-op idempotently. Calling detach on a non-replica is an error.
PUT /clusters/{cluster_id}/actions/detach
Request
Path parameters
cluster_id
: The ID of the cluster to detach.
cURL example
curl -X PUT https://api.crunchybridge.com/clusters/{cluster_id}/actions/detach
-H "Authorization: Bearer $CRUNCHY_API_KEY"
Response
Status: 200
Responds with the standard Cluster
API resource.