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 `ClusterGroupobject`	The cluster group that the cluster belongs to, if any.
`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 `ClusterDiskUsageobject`	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 `null`.
`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 `production` will show a special banner to indicate the higher risk environment. Enum `production`.
`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 `0` to `23` representing the hour of day which maintenance is allowed to start, with `0` representing midnight UTC. Maintenance windows are typically three hours long starting from this hour. A `null` value means that no explicit maintenance window has been set and that maintenance is allowed to occur at any time.
`major_version`		`integer`	The cluster's major Postgres version. For example, `14`.
`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 for a replica cluster. Always `null` for primaries and forks.
`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 `aws`, `azure`, or `gcp`.
`region_id`		`string`	The provider region where the cluster is located.
`replicas`		`array` of `array`	Replicas for the cluster.
`state`	✔	enum `string`	The state of the cluster. This field comes from the cluster service backend and is only populated on cluster info requests. Enum `creating`, `destroying`, `finalizing`, `ready`, `replaying`, `restarting`, `restoring`, `resuming`, `starting`, `suspended`, or `suspending`.
`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.
`variable_backups`		`object` of type `ClusterVariableBackupsobject`	Number of backup retentions for various timeframes.
`zone`	✔	`string`	Name of the zone where the physical server is located. Zones are deployment subpartitions within regions, and common wisdom is that the same way data transfer is faster within a region than between them, it's faster within zones than between different zones in the same region. However, any single zone is more susceptible to failure compared to all of them in aggregate, so deployments should distribute servers between zones for maximum availability. This concept applies to all cloud providers. They're more specifically called "availability zones" for AWS and Azure, and just "zones" on GCP. Not all Azure regions support availability zones (generally the older ones), and this property will be `null` for those.
`cluster_id`	✔	`string` in EID format	In the case of a replica, the ID of the primary cluster. Always `null` for primaries and forks. Deprecated Prefer use of `parent_id`.

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,
            "state": null,
            "storage": 100,
            "tailscale_active": false,
            "team_id": "eaevtjiudzeq7bsqbbpiscund4",
            "updated_at": "2021-07-11T01:02:03Z",
            "variable_backups": {
                "daily": 10,
                "monthly": 0,
                "weekly": 0,
                "yearly": 0
            },
            "zone": null
        }
    ],
    "state": null,
    "storage": 100,
    "tailscale_active": false,
    "team_id": "eaevtjiudzeq7bsqbbpiscund4",
    "updated_at": "2021-07-11T01:02:03Z",
    "variable_backups": {
        "daily": 10,
        "monthly": 0,
        "weekly": 0,
        "yearly": 0
    },
    "zone": "usw2-az4"
}

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 `citus`, or `postgres`.
`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 `aws`, `azure`, or `gcp`.
`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	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).

The `ClusterVariableBackups` object

Number of backup retentions for various timeframes.

Name	Type	Description
`daily`	`integer`	Number of daily backups retained. 10 daily backups are included with all Bridge clusters, but this number may be increased.
`monthly`	`integer`	Number of monthly backups retained. 0 by default (Bridge clusters only come with daily backups), but this number may be increased.
`weekly`	`integer`	Number of weekly backups retained. 0 by default (Bridge clusters only come with daily backups), but this number may be increased.
`yearly`	`integer`	Number of yearly backups retained. 0 by default (Bridge clusters only come with daily backups), but this number may be increased.

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 `provider_id` and `region_id` must not be set as specifying them either would result in an error.
`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 `plan_id` and `region_id` must also be specified. If specified, then `network_id` must not be set as specifying both would result in an error. Enum `aws`, `azure`, or `gcp`.
`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 `network_id` must not be set or `network_id` must be a network that exists in the specified region. If specified, then `network_id` must not be set as specifying both would result in an error unless the target network is a `gcp` based network. If the target network is a `gcp` based network then this field is required.

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.