This page answers the frequently asked questions about CockroachDB Serverless and CockroachDB Dedicated.
General
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?
All non-contract CockroachDB Cloud organizations are given 50M RUs and 10 GiB of storage for free each month. Free resources do not apply to contract customers. Free resources can be spent across all CockroachDB Serverless clusters in an organization and will appear as a deduction on your monthly invoice.
Setting higher resource limits will allow your cluster to scale to meet your application's needs and maintain a high level of performance. If you reach your storage limit, your cluster will be throttled and you will only be able to delete data or increase your storage limit. If you reach your RU limit, your cluster will be disabled until the end of the billing cycle unless you increase your RU limit.
Organizations without billing information on file can only create one cluster. Once you set up billing information, your organization can have up to 200 clusters.
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. An RU is an abstracted metric that represent the size and complexity of requests made to your cluster. See Plan your CockroachDB Serverless Cluster for more information.
Do I have to pay for CockroachDB Serverless?
No, you can create one CockroachDB Serverless cluster for free. The free cluster can use up to 50M RUs and 10 GiB of storage per month. If you need more resources, you can set higher limits for your cluster. You will be charged only for your usage beyond the free threshold.
What regions are available for CockroachDB Serverless clusters?
Refer to CockroachDB Cloud Regions for the regions where CockroachDB Dedicated and clusters can be deployed. A multi-region Serverless cluster can have a maximum of six regions. To express interest in additional regions, contact Support or your Cockroach Labs account team.
How can I estimate how many RUs my workload will consume?
The best way to estimate your resource usage is to set resource limits 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.
A typical SELECT query consumes between 1 and 15 RUs, depending on the amount of data it scans and returns. A typical INSERT or UPDATE statement consumes between 10 and 25 RUs, depending on the amount of data it inserts or updates. To estimate the RU consumption of individual SQL statements, you can use the EXPLAIN ANALYZE SQL statement. For an example, see Example Request Unit calculation.
How can I reduce the number of RUs my workload consumes?
Make sure your queries have been optimized for performance, and follow the SQL best practices recommendations.
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 CockroachDB 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 resource limits 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, the cluster will experience a spike in RU usage. You can disable automatic statistics collection to avoid these RU bursts, but this may cause the cost-based optimizer to choose inefficient statement plans based on outdated statistics.
Refreshing the Cloud Console will also consume RUs.
What is the cold start latency of a CockroachDB 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. Note that cold starts consume RUs, so you will see a spike in usage.
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.
How do I get the SQL endpoint for a specific region of my multi-region cluster?
This information is not currently available in the CockroachDB Cloud Console. The connection string provided in the Console uses a geolocation routing policy to automatically route clients to the nearest region. However, if you need to determine region-specific DNS names, you can do either of the following:
Make an API request to GET /api/v1/clusters/{cluster_id}. The SQL endpoint for each region will be visible in regions -> sql_dns.
Or, manually create the region-specific DNS names using your cloud provider and the single region names. For example, a GCP Serverless cluster with the DNS name <routing-id>.h4f.cockroachlabs.cloud might have the following regional DNS names:
<routing-id>.h4f.gcp-us-east1.cockroachlabs.cloud<routing-id>.h4f.gcp-us-west2.cockroachlabs.cloud<routing-id>.h4f.gcp-europe-west2.cockroachlabs.cloud.
Security
Is my cluster secure?
Yes, intra-cluster communications are secured using certificates, 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 CA certificate and configure your client to use that certificate because the client will connect using the system root CA certificates.
However, some drivers and ORMs don't use the system root CA certificates. In those cases, you need to download a root CA certificate and configure your client to use that certificate to verify the cluster's identity when connecting to it. You can download the root CA 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 CA 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. We recommend using sslmode=verify-full so that your cluster is not vulnerable to man-in-the-middle attacks.
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 is encrypted-at-rest using persistent disk encryption.
- Data stored in clusters running in AWS is encrypted-at-rest using EBS encryption.
As noted above, we rely on the cloud provider's encryption implementation. We do not enable CockroachDB's internal implementation of encryption-at-rest.
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.
Cluster maintenance
Can I upgrade my free CockroachDB Serverless cluster's performance?
Yes, you can upgrade your cluster through the Console by increasing your resource limits and entering billing information if you haven't already.
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.
Product features
Do you have a UI? How can I see details?
Yes, you can view and your clusters in the CockroachDB Cloud Console. However, some DB Console pages are not currently available for CockroachDB Serverless clusters.
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 IMPORT and EXPORT from my cluster?
Yes, you can IMPORT and EXPORT on CockroachDB Serverless clusters. You can use a cloud storage provider or set up a userfile location.
We don't recommend userfile for EXPORT operations. You can either use cloud storage or export data to a local CSV file by using cockroach sql --execute. For example:
$ cockroach sql \
--url 'postgres://{username}:{password}@{host}:26257?sslmode=verify-full&sslrootcert={path/to/certs_dir}/cc-ca.crt' \
--execute "SELECT * FROM db.table" --format=csv > /Users/{username}/{path/to/file}/table.csv
Is change data capture available to me?
Yes, CockroachDB Serverless clusters have access to both Core changefeeds and Enterprise changefeeds.
You can run a "sinkless" changefeed to the current SQL session with EXPERIMENTAL CHANGEFEED FOR or CREATE CHANGEFEED, or you can run a changefeed to a configurable sink.
Can I backup my CockroachDB Serverless cluster? Does Cockroach Labs take backups of my cluster?
CockroachDB Cloud automatically runs full backups daily for every CockroachDB Serverless cluster. Full backups are retained for 30 days. CockroachDB Cloud does not take incremental backups of CockroachDB Serverless clusters, or allow database or table level restores from automatic full cluster backups. However, you can also take manual backups locally and store them in your cloud storage buckets using the BACKUP statement.
Once a cluster is deleted, Cockroach Labs retains the full backups for 30 days. The retained backups are not available for restore using the Cloud Console. To restore a backup from a deleted cluster, you must contact the Cockroach Labs Support team. If an organization is deleted, you will lose access to all of the managed-service backups that Cockroach Labs has taken of the cluster.
Was this helpful?
