What do moving vans have to do with databases? Think of it this way:
Imagine you’re living in a cozy studio apartment – that’s CockroachDB Basic. It’s affordable, easy to manage, and serves your needs for now. But as time passes, you accumulate more furniture (data), need better amenities (performance), and decide to upgrade to a bigger house – you’ve leveled up to CockroachDB Standard.
Conversely, perhaps you no longer need all the extra space and want to downsize. The key is moving seamlessly without disrupting your daily life.
That’s where the CockroachCloud API comes in: It acts like a professional moving service, helping you transition between CockroachDB Basic and Standard plans with zero downtime. This article will guide you through using the CockroachCloud API to migrate your cluster efficiently, and highlight scenarios where backup and restore might be a better option.
When to use the CockroachCloud API vs. backup & restore
The CockroachCloud API is perfect for seamless upgrades and downgrades within the same region, as it requires no downtime. However, backup and restore can also be used for upgrading or downgrading within the same region, particularly if you prefer a fresh start or need to rollback from a ransomware attack, for example.
If you need to migrate to a different region, backup and restore is the only option, since the API does not currently support region transfers.
Step-by-Step: Migrating a CockroachDB cluster with the CockroachCloud API
Step 1: Retrieve your cluster ID
First, fetch your cluster ID by running:
curl --request GET \
--url 'https://cockroachlabs.cloud/api/v1/clusters' \
--header 'Authorization: Bearer <API_KEY>'
Copy the CLUSTER_ID from the appropriate cluster.
Step 2: Upgrading from basic to standard
If you need higher performance, private networking, provisioned compute, manual version control, metrics/logs export, flexible RPO and retention for managed backups, or ISO or SOC2 compliance, upgrade to a Standard cluster using:
curl --request PATCH \
--url https://cockroachlabs.cloud/api/v1/clusters/<CLUSTER_ID> \
--header 'Authorization: Bearer <API_KEY>' \
--json '{"plan": "STANDARD", "serverless": {"usage_limits": {"provisioned_virtual_cpus": "12"}}}'
Note: Provisioned virtual cpus can be any value from 2–60.
Note: If your Basic cluster is hosted on an older version, it won’t support features like PrivateLink or Private Endpoint even after upgrading.
Step 3: Downgrading from standard to basic
If you need to cut costs and your workload allows, downgrade using one of the following commands:
Without specific limits:
curl --request PATCH \
--url https://cockroachlabs.cloud/api/v1/clusters/<CLUSTER_ID> \
--header 'Authorization: Bearer <API_KEY>' \
--json '{
"plan": "BASIC",
"serverless": {
"usage_limits": {}
}
}'
With custom request unit & storage limits:
curl --request PATCH \
--url https://cockroachlabs.cloud/api/v1/clusters/<CLUSTER_ID> \
--header 'Authorization: Bearer <API_KEY>' \
--json '{
"plan": "BASIC",
"serverless": {
"usage_limits": {
"request_unit_limit": "50000000",
"storage_mib_limit": "10000"
}
}
}'
Note: The limits you set for RUs and Storage will be for a monthly basis. 50 million RUs and 10 GiB storage are free per month.
Key considerations when migrating
PrivateLink & Private Endpoint Connectivity: If you’re migrating from Basic to Standard but your cluster is on older infrastructure, you won’t be able to enable these features. You may need to create a new cluster instead.
Zero Downtime: The API enables in-place upgrades and downgrades without service interruptions.
Backup & Restore Flexibility: You can also use backup and restore for upgrades or downgrades within the same region if you prefer a clean migration.
Cost Optimization: Downgrading to Basic helps control costs if high performance is no longer needed.
Regional Migrations: If you need to move to a different region, use backup and restore instead of the API.
Note: Migrating clusters from Basic to Standard and vice versa is now available via the Cloud Console UI as an alternative to the CockroachCloud API.
Move easily between CockroachDB Cloud plans
By understanding when to use the API vs. backup and restore, you can make informed decisions that align with your business needs.
Just like upgrading from a studio to a house or downsizing to something cozier, moving between CockroachDB Basic and Standard should be seamless. The CockroachCloud API makes it simple and efficient to change your CockroachDB pricing plan, minimizing downtime while optimizing costs and performance.
Experience it for yourself! Get hands-on with CockroachDB’s free cloud offering today.
Ben Sherrill is a Sales Engineer for Cockroach Labs.
