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

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_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
    },
    "id": "rvf73a77ozfsvcttryebfrnlem",
    "is_ha": 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_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 next_cursor from the last page into this field to get the next one.

limit integer

The maximum number of items to return on the page. Defaults to 100 with a minimum of 1 and a maximum of 100.

order enum string

The order of pagination. asc for ascending or desc for descending. Defaults to asc.

Enum asc, or desc.

order_field string

The name of the field on which to paginate like id or name. Supported fields are specific to each endpoint, and it’s not possible to specify any arbitrary name. See the documentation for each specific list endpoint to see which fields it supports. Defaults to id for most resources.

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_ACCESS_TOKEN"

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_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_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 14.

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 postgres_version_id instead which will also accept a major version number value.

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_ACCESS_TOKEN"
    -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_ACCESS_TOKEN"

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
maintenance_­window_­start integer

The desired 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.

Send -1 to unset the maintenance window.

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_ACCESS_TOKEN"
    -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_ACCESS_TOKEN"

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_ACCESS_TOKEN"

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 creating, destroying, ready, or restarting.

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 ha_change, major_version_upgrade, or resize.

state enum string

The state of the ongoing resize.

One of ready, scheduled, in_progress, or failing_over for a major version upgrade or resize.

One of enabling_ha, waiting_for_ha_standby or disabling_ha for an HA change.

Enum disabling_ha, enabling_ha, failing_over, in_progress, ready, scheduled, or waiting_for_ha_standby.

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 oldest_backup_at under cluster status) and the current time.

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_ACCESS_TOKEN"
    -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 server which restarts the underlying server and everything on it.

Enum postgres, or server.

cURL example

curl -X PUT https://api.crunchybridge.com/clusters/{cluster_id}/actions/restart
    -H "Authorization: Bearer $CRUNCHY_ACCESS_TOKEN"

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_ACCESS_TOKEN"

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."
}

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_ACCESS_TOKEN"

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_ACCESS_TOKEN"

Response

Status: 200

Responds with the standard Cluster API resource.