Page contents

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_id âś” string in EID format

In the case of a replica, the ID of the primary cluster. Always null for primaries and forks.
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 null.
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.
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 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
    },
    "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",
    "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,
            "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",
            "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).

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.
network_id string in EID format

The ID of the network where the new replica should be created. The cluster is created in the same network as its primary if left empty.
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 target cluster’s plan. If specified, then provider_id and region_id must also be specified.
provider_id string

The cloud provider in which to create the replica.

If not specified, defaults to the target cluster’s provider. If specified, then plan_id and region_id must also be specified.
region_id string

The provider region in which to create the replica.

If not specified, defaults to the target cluster’s region. If specified, then provider_id and plan_id must also be specified.

Example request body

{
    "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 '{"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.

Destroy cluster replica

Delete a read-replica database cluster.

DELETE /clusters/{cluster_id}/replicas/{replica_id}

Request

Path parameters

  • cluster_id: Unique ID of the cluster which the replica belongs to.
  • replica_id: Unique ID of the replica to destroy.

cURL example

curl -X DELETE https://api.crunchybridge.com/clusters/{cluster_id}/replicas/{replica_id}
    -H "Authorization: Bearer $CRUNCHY_API_KEY"

Response

Status: 200

Responds with the standard Cluster API resource.