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

NameNullableTypeDescription
idstring in EID format

The unique ID of the cluster.

cluster_groupobject of type ClusterGroupobject

The cluster group that the cluster belongs to, if any.

cluster_idstring in EID format

In the case of a replica, the ID of the primary cluster. Always null for primaries and forks.

Deprecate: Prefer use of parent_id.

cpuinteger

The number of CPU units on the cluster's instance.

created_atstring of date/time formatted as RFC 3339

Time at which the cluster was originally created.

disk_usageobject 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.

environmentenum 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.

hoststring

The hostname of the cluster.

is_haboolean

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_protectedboolean

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_suspendedboolean

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_idstring in EID format

The ID of the keychain used by the cluster for encrypting its data.

maintenance_window_startinteger

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_versioninteger

The cluster's major Postgres version. For example, 14.

memorynumber

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.

namestring

A human-readable name for the cluster.

network_idstring in EID format

The ID of the network where the cluster is located.

parent_idstring in EID format

The ID of the primary or parent cluster or a replica cluster. Always null for primaries and forks.

plan_idstring

The ID of the cluster's plan. Determines instance, CPU, and memory.

postgres_version_idstring in EID format

The ID of the cluster's major Postgres version.

provider_idenum string

The cloud provider where the cluster is located.

Enum aws, azure, or gcp.

region_idstring

The provider region where the cluster is located.

replicasarray of array

Replicas for the cluster.

reset_stats_weeklyboolean

Whether pg_stat_statements is automatically reset on the cluster on a weekly basis.

storageinteger

The amount of storage available to the cluster in GB (gigabytes).

tailscale_activeboolean

Indicates whether tailscale is active for the cluster.

team_idstring in EID format

The ID of the team that the cluster belongs to.

updated_atstring 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.

NameNullableTypeDescription
idstring in EID format

Unique ID of the cluster group.

clustersarray 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.

kindenum string

The kind of cluster group.

Enum citus, or postgres.

namestring

A human-friendly name of the cluster group.

network_idstring in EID format

ID of the network on which the cluster group is located.

provider_idenum string

ID of the provider on which the cluster group is located.

Enum aws, azure, or gcp.

region_idstring

ID of the region where the cluster group is located.

team_idstring in EID format

ID of the team which the cluster group belongs to.

The ClusterDiskUsage object

Contains information about a cluster's disk usage.

NameNullableTypeDescription
disk_available_mbinteger

Available disk left in MB (megabytes).

disk_total_size_mbinteger

Total disk size in MB (megabytes).

disk_used_mbinteger

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

NameRequiredTypeDescription
namestring

A human-readable name for the replica.

cluster_group_idstring in EID format

The ID of the cluster group that the replica should be assigned to.

keychain_idstring in EID format

The ID of the keychain that should be used by the replica for encrypting its data.

network_idstring 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_idstring

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_idenum 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_idstring

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.