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

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.

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.

Deprecated: Prefer referring to disk usage via metric directly using the disk-usage metric view. The metrics there reflect a more accurate view of current disk size that's more suitable for public consumption. This version may be skewed by internal partitions managed by Bridge which may lead to misleading disk numbers.

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.

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_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_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_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_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_id✔enum 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.

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.

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.

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

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_id✔enum 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).

The ClusterVariableBackups object

Number of backup retentions for various timeframes.

NameNullableTypeDescription
dailyinteger

Number of daily backups retained.

10 daily backups are included with all Bridge clusters, but this number may be increased.

monthlyinteger

Number of monthly backups retained.

0 by default (Bridge clusters only come with daily backups), but this number may be increased.

weeklyinteger

Number of weekly backups retained.

0 by default (Bridge clusters only come with daily backups), but this number may be increased.

yearlyinteger

Number of yearly backups retained.

0 by default (Bridge clusters only come with daily backups), but this number may be increased.

List clusters

List clusters for all teams that the account is a member.

For listing the clusters of a specific team use the team_id query parameter.

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

NameRequiredTypeDescription
cursorstring

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.

Cursor values depend on the field in order_field. Cursors will often be the primary IDs of object, but when ordering on another field like name, they'll be names (or another value) instead.

limitinteger

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

orderstring

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

Enum asc, or desc.

order_fieldstring

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.

Enum id, or name.

team_idstring

Optional filter for listing only the clusters for a specific team that the authenticated user is a member.

cURL example

curl -X GET https://api.crunchybridge.com/clusters
    -H "Authorization: Bearer $CRUNCHY_API_KEY"

Response

Status: 200

Response for listing clusters.

Content type: application/json

NameNullableTypeDescription
clustersarray of array

List of clusters for this page.

has_moreboolean

Indicates whether or not there are more resources to page through in the collection.

next_cursor✔string

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",
            "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"
        }
    ],
    "has_more": false,
    "next_cursor": null
}

Create cluster

Create a database cluster.

POST /clusters

Request body schema

Content type: application/json

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

team_id✔string in EID format

The ID of the team that the cluster should belong to.

Admin privilege on the team is required.

cluster_group_idstring in EID format

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

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.

is_haboolean

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.

keychain_idstring in EID format

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

maintenance_window_startinteger

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. Maintenance windows are three hours starting from the specified hour.

network_idstring 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_idinteger, or string``undefined

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. May be omitted, and if it is, the new server will inherit the current default Postgres version.

provider_idenum string

The cloud provider in which to create the cluster.

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

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.

storageinteger

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

major_versioninteger

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

{
    "cluster_group_id": null,
    "keychain_id": null,
    "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_API_KEY"
    -H "Content-Type: application/json"
    -d '{"cluster_group_id":null,"keychain_id":null,"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_API_KEY"

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

NameRequiredTypeDescription
cluster_group_idstring in EID format

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

dashboard_settingsobject of type ClusterDashboardSettingsobject

Update dashboard-specific settings.

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.

Set to an empty string to clear the value.

Enum production.

is_protectedboolean

Make the cluster protected, which means that it can't be destroyed until it's explicitly set as unprotected.

maintenance_window_startinteger

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. Maintenance windows are three hours starting from the specified hour.

Send -1 to unset the maintenance window.

namestring

Name is the new human-readable name to be assigned to the cluster.

variable_backupsobject of type ClusterUpdateRequestVariableBackupsobject

Number of backup retentions for various timeframes.

Example request body

{
    "cluster_group_id": null,
    "maintenance_window_start": 3,
    "name": "new-cluster-name",
    "variable_backups": null
}

cURL example

curl -X PATCH https://api.crunchybridge.com/clusters/{cluster_id}
    -H "Authorization: Bearer $CRUNCHY_API_KEY"
    -H "Content-Type: application/json"
    -d '{"cluster_group_id":null,"maintenance_window_start":3,"name":"new-cluster-name","variable_backups":null}'

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

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 about the cluster that's retrieved from the Bridge platform's backend state machine responsible for managing Postgres instances, rather than information that's stored out of band in the API component, 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_API_KEY"

Response

Status: 200

Response for getting a cluster's online status.

Content type: application/json

NameNullableTypeDescription
disk_usageobject of type ClusterDiskUsageobject

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 time. May be null if no backup has occurred yet.

oldest_backup_lsn✔string

The cluster's oldest backup LSN. May be null if no backup has occurred yet.

ongoing_upgradeobject of type ClusterUpgradeobject

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, finalizing, ready, replaying, restarting, restoring, resuming, starting, suspended, or suspending.

Example

{
    "disk_usage": {
        "disk_available_mb": 94948,
        "disk_total_size_mb": 100213,
        "disk_used_mb": 133
    },
    "oldest_backup_at": "2021-07-11T01:02:03Z",
    "oldest_backup_lsn": "0/1D43D7A8",
    "ongoing_upgrade": {
        "cluster_id": "rvf73a77ozfsvcttryebfrnlem",
        "operations": [
            {
                "flavor": "ha_change",
                "starting_from": null,
                "state": "waiting_for_ha_standby"
            },
            {
                "flavor": "resize",
                "starting_from": null,
                "state": "in_progress"
            }
        ],
        "team_id": "eaevtjiudzeq7bsqbbpiscund4"
    },
    "state": "ready"
}

The ClusterUpgrade object

Response for the status of a cluster upgrade.

NameNullableTypeDescription
cluster_idstring in EID format

ID of the cluster being upgraded.

operationsarray of array

Contains ongoing upgrade operations. Empty if there are no ongoing upgrade operations.

team_idstring in EID format

ID of the team which the cluster being upraded belongs to.

Example

{
    "cluster_id": "rvf73a77ozfsvcttryebfrnlem",
    "operations": [
        {
            "flavor": "ha_change",
            "starting_from": null,
            "state": "waiting_for_ha_standby"
        },
        {
            "flavor": "resize",
            "starting_from": null,
            "state": "in_progress"
        }
    ],
    "team_id": "eaevtjiudzeq7bsqbbpiscund4"
}

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

NameRequiredTypeDescription
name✔string

A human-readable name for the fork.

is_haboolean

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.

keychain_idstring in EID format

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

network_idstring in EID format

The ID of the network where the new fork should be created.

If not specified, the cluster is created in a new network.

plan_idstring

The ID of the plan with which to create the fork. Determines instance, CPU, and memory.

If not specified, defaults to the target cluster's plan.

provider_idenum string

The cloud provider in which to create the fork.

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

Enum aws, azure, or gcp.

region_idstring

The provider region in which to create the fork.

If not specified, defaults to the target 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.

storageinteger

The amount of storage to make available to the fork in GB (gigabytes). The fork is created with the same storage size as the parent cluster if left empty.

target_lsnstring

The LSN at which to fork from.

If specified, must be between the cluster's oldest backup LSN (see oldest_backup_lsn under cluster status) and the current LSN.

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

Example request body

{
    "keychain_id": null,
    "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_API_KEY"
    -H "Content-Type: application/json"
    -d '{"keychain_id":null,"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.

Disable high availability

Disable high availability on a cluster.

PUT /clusters/{cluster_id}/actions/disable-ha

Request

Path parameters

  • cluster_id: ID of the cluster for which to disable high availability.

cURL example

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

Response

Status: 200

An ongoing upgrade operation (like a version upgrade or resize) within a database cluster.

Content type: application/json

NameNullableTypeDescription
flavorenum string

The kind of upgrade.

Enum ha_change, maintenance, major_version_upgrade, or resize.

starting_from✔string of date/time formatted as RFC 3339

For a maintenance operation, the time after which the maintenance is scheduled.

stateenum string

The state of the ongoing resize.

One of creating, 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 canceling, creating, destroying, disabling_ha, enabling_ha, failing_over, finalizing, in_progress, ready, replaying, restarting, restoring, resuming, starting, suspended, suspending, or waiting_for_ha_standby.

Enable high availability

Enable high availability on a cluster.

PUT /clusters/{cluster_id}/actions/enable-ha

Request

Path parameters

  • cluster_id: ID of the cluster for which to enable high availability.

cURL example

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

Response

Status: 200

An ongoing upgrade operation (like a version upgrade or resize) within a database cluster.

Content type: application/json

NameNullableTypeDescription
flavorenum string

The kind of upgrade.

Enum ha_change, maintenance, major_version_upgrade, or resize.

starting_from✔string of date/time formatted as RFC 3339

For a maintenance operation, the time after which the maintenance is scheduled.

stateenum string

The state of the ongoing resize.

One of creating, 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 canceling, creating, destroying, disabling_ha, enabling_ha, failing_over, finalizing, in_progress, ready, replaying, restarting, restoring, resuming, starting, suspended, suspending, or waiting_for_ha_standby.

Ping

Ping a cluster by remoting into it and executing a simple query inside its Postgres database. This endpoint provides an easy way of checking a cluster's liveliness.

PUT /clusters/{cluster_id}/actions/ping

Request

Path parameters

  • cluster_id: The ID of the cluster to ping.

cURL example

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

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

NameNullableTypeDescription
messagestring

The message of the response.

Example

{
    "message": "Server will restart momentarily."
}

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

NameRequiredTypeDescription
serviceenum 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_API_KEY"

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: The ID of the cluster to resume.

cURL example

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

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

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

NameNullableTypeDescription
messagestring

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: The ID of the cluster to suspend.

cURL example

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

Response

Status: 200

Responds with the standard Cluster API resource.

Connect to a Tailscale network

Connects a cluster to a Tailscale network (tailnet) similarly to having run tailscale up.

The request takes a Tailscale auth key to authorize the request, which can be generated from Tailscale's keys page if you are a network admin. Auth keys are only persisted in Bridge only as long as needed to be handed off to target Postgres servers, and are encrypted during that period. Even so, given their sensitivity, we still recommend generating a short-lived one to minimize the risk of accidental exposure.

We also encourage you to provision an auth key with an ACL tag like crunchy that an admin has preconfigured with desired access permissions. By doing so, the cluster's permissions will be limited to those specified by the tag immediately on joining your tailnet.

See the Tailscale docs on tailnets for more information.

PUT /clusters/{cluster_id}/actions/tailscale-connect

Request

Path parameters

  • cluster_id: The ID of the cluster.

Request body schema

Content type: application/json

NameRequiredTypeDescription
auth_keystring

A one-off Tailscale auth key used to authorize the cluster to join a tailscale network. If provided, then tailscale_oauth_client_id MUST be null.

See Tailscale auth keys.

tailscale_oauth_client_idstring in EID format

The ID of the Tailscale OAuth Client use to join a tailscale network. If provided then auth_key MUST be null.

See Tailscale OAuth clients.

Example request body

{
    "auth_key": "tskey-abcdef1432341818",
    "tailscale_oauth_client_id": null
}

cURL example

curl -X PUT https://api.crunchybridge.com/clusters/{cluster_id}/actions/tailscale-connect
    -H "Authorization: Bearer $CRUNCHY_API_KEY"
    -H "Content-Type: application/json"
    -d '{"auth_key":"tskey-abcdef1432341818","tailscale_oauth_client_id":null}'

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

NameNullableTypeDescription
messagestring

The message of the response.

Example

{
    "message": "Server will restart momentarily."
}

Disconnect from a Tailscale network

Disconnects a cluster from a previously connected Tailscale network (tailnet) similarly to having run tailscale down.

See the Tailscale docs on tailnets for more information.

PUT /clusters/{cluster_id}/actions/tailscale-disconnect

Request

Path parameters

  • cluster_id: The ID of the cluster.

cURL example

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

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

NameNullableTypeDescription
messagestring

The message of the response.

Example

{
    "message": "Server will restart momentarily."
}