This page answers the frequently asked questions about CockroachDB serverless and CockroachDB dedicated.
What is CockroachDB serverless?
CockroachDB serverless delivers free and pay-as-you-go CockroachDB clusters for you and your organization. It is a managed instance of CockroachDB that lets you start using your database immediately and auto-scales based on your application traffic.
For a deeper dive into serverless database concepts and how to get started with CockroachDB serverless, take the free Introduction to Serverless Databases and CockroachDB serverless course on Cockroach University.
How do I start using CockroachDB serverless?
To get started with CockroachDB serverless, sign up for a CockroachDB Cloud account, click Create Cluster, then click Create your free cluster. Your cluster will be ready in 20-30 seconds. For more information, see Quickstart.
What are the usage limits of CockroachDB serverless?
Clusters start with 10M RUs of free burst capacity each month and earn 100 RUs per second up to a maximum of 250M free RUs per month. Earned RUs can be used immediately or accumulated. If you use all of your burst capacity and earned RUs, your cluster will revert to baseline performance.
If you set a spend limit, your cluster will not be throttled to baseline performance once you use all of your free earned RUs. Instead, it will continue to use burst performance as needed until you reach your spend limit. If you reach your spend limit, your cluster will revert to the baseline performance of 100 RUs per second.
You can create a maximum of five Serverless clusters per organization.
What is a Request Unit?
With CockroachDB serverless, you are charged for the storage and activity of your cluster. All cluster activity, including SQL queries, bulk operations, and background jobs, is measured in Request Units, or RUs. RUs are an abstracted metric that represent the size and complexity of requests made to your cluster. See Learn About Request Units for more information.
Do I have to pay for CockroachDB serverless?
No, you can create a Serverless cluster that is free forever. If you choose to set a spend limit for your cluster, you will only be charged for the resources you use up to your spend limit.
How can I estimate how many RUs my workload will consume?
The best way to estimate your resource usage is to enter a spend limit you're comfortable with and run your workload. You can see the RUs and storage your cluster has used in the Usage this month section of the Cluster Overview page. Once enough usage data is available, you can also see a graph of your monthly resource usage and recommended spend limit on the Edit cluster page.
How can I reduce the number of RUs my workload consumes?
For example, if your statement uses filters in a
WHERE clause but you don't have indexes on the filter columns, you will consume more RUs because the statement causes a full table scan when doing the join. Use the
EXPLAIN statement with your queries to find full table scans or other costly operations. Adding the correct index will result in better performance for the statement, and also consume fewer RUs.
The size of the data in your columns also directly affects RU consumption and query performance. For example, Cockroach Labs recommends keeping
JSONB column data under 1 MB to maximize performance. Statements that read or write large
JSONB values will consume more RUs as the storage and I/O costs are higher. Adding GIN indexes or partial GIN indexes when querying
JSONB columns can help improve performance and reduce the RU usage of these statements.
What can I use CockroachDB serverless for?
Free CockroachDB serverless clusters can be used for proofs-of-concept, toy programs, or to use while completing Cockroach University.
For examples of applications that use free clusters, check out the following Hack the North projects:
Paid Serverless clusters include additional resources to maintain higher performance. They are ideal for applications with varying workloads and spikes in traffic.
How do I connect to my cluster?
To connect to a cluster, download the CA certificate, and then generate a connection string or parameters. You can use this information to connect to your cluster through the CockroachDB SQL client or a PostgreSQL-compatible driver or ORM. For more details, see Connect to Your CockroachDB serverless Cluster.
I created a CockroachCloud Free (beta) cluster before CockroachDB serverless was available. Can I still use my cluster?
Yes, your free cluster has been automatically migrated to CockroachDB serverless. Your ability to use your cluster should not be affected, and you will now have the option to add a spend limit for your cluster with no downtime.
Why does my RU usage briefly spike when I'm running a steady workload?
CockroachDB automatically collects statistics in a background process when certain conditions are met (for example, when more than 20% of rows in a table are modified). The statistics are used by the cost-based optimizer to tune statements for higher performance.
When automatic statistics collection starts your cluster may consume RUs above the 100 RUs per second baseline when your workload is otherwise consuming RUs below the baseline. You can turn off automatic statistics collection to avoid these RU bursts, but the cost-based optimizer may choose inefficient statement plans as it doesn't have access to the latest statistics.
What is the cold start latency of a Serverless cluster?
When a CockroachDB serverless cluster is idle, it will scale down to zero and consume no RUs. When the cluster becomes active again it will begin serving requests within a fraction of a second, typically around 600 milliseconds.
Why is disk usage increasing despite lack of writes?
CockroachDB serverless clusters regularly store information about their own health and status in system tables. Once these tables hit their retention limit, storage will level off. However, the amount of stored data should be very small in relation to the overall storage limits.
Is my cluster secure?
Yes, we use separate certificate authorities for each cluster, and all connections to the cluster over the internet use TLS 1.3.
What certificates do I need to connect to my cluster?
All connections to CockroachDB serverless require SSL encryption. When connecting to your cluster using the CockroachDB SQL client or many drivers and ORMs, you don't need to download a root certificate and configure your client to use that certificate because the client will connect using the system root certificates. If you configure your client to use SSL and to verify the certificates (for example, by setting
sslmode=verify-full in your connection string), your connection will be encrypted.
However, some drivers and ORMs don't use the system root certificates. In those cases, you need to download a root certificate file and configure your client to use that certificate when connecting to your cluster. You can download the certificate by following the instructions in the CockroachDB Cloud Console. Configure your client to use this certificate (for example, by setting
sslrootcert=<path to the root certificate> in your connection string) and to use SSL (for example, by setting
sslmode=verify-full in your connection string) to connect to your cluster.
See Connect to a CockroachDB Cluster for detailed information on connecting to your cluster using CockroachDB supported languages, drivers, and ORMs
Is encryption-at-rest enabled on CockroachDB serverless?
Yes. All data on CockroachDB Cloud is encrypted-at-rest using the tools provided by the cloud provider that your cluster is running in.
- Data stored in clusters running in GCP are encrypted-at-rest using persistent disk encryption.
- Data stored in clusters running in AWS are encrypted-at-rest using EBS encryption-at-rest.
Because we are relying on the cloud provider's encryption implementation (as noted above), we do not enable CockroachDB's internal implementation of encryption-at-rest. This means that encryption will appear to be disabled in the DB Console, since the console is unaware of cloud provider encryption.
Is there a public API for CockroachDB Cloud?
Yes, see the Cloud API page for more information. Note that the Cloud API is a REST interface, and we do not currently support an HTTP data API. We’re always looking for design partners and customer input for our features, so please contact us if you have specific API requirements.
Is my cluster isolated? Does it share resources with any other clusters?
CockroachDB serverless is a multi-tenant offering and resources are shared between clusters. For more information, see CockroachDB serverless Architecture.
Can I upgrade my free CockroachDB serverless cluster's performance?
Can I upgrade the version of CockroachDB my CockroachDB serverless cluster is running on?
No, CockroachDB serverless clusters are upgraded automatically for you. You can see what version of CockroachDB your cluster is running in the CockroachDB Cloud Console or in the latest release notes.
Do you have a UI? How can I see details?
Are all CockroachDB features available in CockroachDB serverless clusters?
There are some features of CockroachDB that are unsupported or partially supported in CockroachDB serverless clusters. Cockroach Labs intends to eliminate these feature gaps in future releases of CockroachDB serverless. See Unsupported Features in CockroachDB Serverless for more details.
Can I run bulk operations such as
EXPORT from my cluster?
Yes, you can run bulk operations on Serverless clusters. You must add billing information to your organization to run bulk operations using cloud storage providers, but you can leave your spend limit at the $0 default. If you don't have billing set up for your organization, you can set up a
userfile location for bulk operations.
We don't recommend
EXPORT operations. You can either add billing information to your organization to enable access to cloud storage, or export data to a local CSV file.
Is change data capture available to me?
Yes, CockroachDB serverless clusters have access to both Core changefeeds and Enterprise changefeeds once you have billing information on file for your organization, even if you leave your spend limit at the $0 default.
If you don't have billing information on file for your organization, you can run a "sinkless" changefeed to the current SQL session with
EXPERIMENTAL CHANGEFEED FOR or
CREATE CHANGEFEED. Once you enter billing information, even if you have a spend limit of $0, you can also run a changefeed to a configurable sink.
Creating a changefeed for a CockroachDB serverless cluster without first entering billing information will cause the following error:
pq: Outbound IO is disabled by configuration.
Can I backup my CockroachDB serverless cluster? Does Cockroach Labs take backups of my cluster?
The Backups page allows you to restore your cluster from automatic full cluster backups, which are performed hourly and stored for 30 days. CockroachDB Cloud does not take incremental backups of Serverless clusters, or allow database or table level restores from automatic full cluster backups. However, you can also backup and restore your CockroachDB serverless cluster manually. If you don't have billing information on file for your organization, you can take backups locally to
userfile. Once you enter billing information, even if you leave your spend limit at the $0 default, you can also backup to cloud storage.
Running a bulk operation to cloud storage from a CockroachDB serverless cluster without first entering billing information will cause the following error:
external network access is disabled.