This page documents best practices for unit testing applications built on CockroachDB in a local environment.
If you are deploying a self-hosted cluster, see the Production Checklist for information about preparing your cluster for production.
The settings described on this page are not recommended for use in production clusters. They are only recommended for use during unit testing and continuous integration testing (CI).
Use a local, single-node cluster with in-memory storage
The cockroach start-single-node command below starts a single-node, insecure cluster with in-memory storage. Using in-memory storage improves the speed of the cluster for local testing purposes.
cockroach start-single-node --insecure --store=type=mem,size=0.25 --advertise-addr=localhost
We recommend the following additional cluster settings and SQL statements for improved performance during functional unit testing and continuous integration testing. In particular, some of these settings will increase the performance of schema changes, since repeated creation and dropping of schemas are common in automated testing.
| Setting | Value | Description |
|---|---|---|
kv.range_merge.queue_interval |
50ms |
Frequent CREATE TABLE or DROP TABLE creates extra ranges, which we want to merge more quickly. In real usage, range merges are rate limited because they require rebalancing. |
jobs.registry.interval.gc |
30s |
CockroachDB executes internal queries that scan the jobs table. More schema changes create more jobs, which we can delete faster to make internal job queries faster. |
jobs.registry.interval.cancel |
180s |
Timing of an internal task that queries the jobs table. For testing, the default is too fast. |
jobs.retention_time |
15s |
More schema changes create more jobs, which affects job query performance. We don’t need to retain jobs during testing and can set a more aggressive delete policy. |
sql.stats.automatic_collection.enabled |
false |
Turn off statistics collection, since automatic statistics contribute to table contention alongside schema changes. Each schema change triggers an asynchronous auto statistics job. |
ALTER RANGE default CONFIGURE ZONE USING "gc.ttlseconds" |
600 |
Faster descriptor cleanup. For more information, see ALTER RANGE. |
ALTER DATABASE system CONFIGURE ZONE USING "gc.ttlseconds" |
600 |
Faster jobs table cleanup. For more information, see ALTER DATABASE. |
To change all of the settings described above at once, run the following SQL statements:
SET CLUSTER SETTING kv.range_merge.queue_interval = '50ms';
SET CLUSTER SETTING jobs.registry.interval.gc = '30s';
SET CLUSTER SETTING jobs.registry.interval.cancel = '180s';
SET CLUSTER SETTING jobs.retention_time = '15s';
SET CLUSTER SETTING sql.stats.automatic_collection.enabled = false;
SET CLUSTER SETTING kv.range_split.by_load_merge_delay = '5s';
ALTER RANGE default CONFIGURE ZONE USING "gc.ttlseconds" = 600;
ALTER DATABASE system CONFIGURE ZONE USING "gc.ttlseconds" = 600;
These settings are not recommended for performance benchmarking of CockroachDB since they will lead to inaccurate results.
Scope tests to a database when possible
It is better to scope tests to a database than to a user-defined schema due to inefficient user-defined schema validation. The performance of user-defined schema validation may be improved in a future release.
Log test output to a file
By default, cockroach start-single-node logs cluster activity to a file with the default logging configuration. When you specify the --store=type=mem flag, the command prints cluster activity directly to the console instead.
To customize logging behavior for local clusters, use the --log flag:
cockroach start-single-node --insecure --store=type=mem,size=0.25 --advertise-addr=localhost --log="{file-defaults: {dir: /path/to/logs}, sinks: {stderr: {filter: NONE}}}"
The log flag has two suboptions:
file-defaults, which specifies the path of the file in which to log events (/path/to/logs).sinks, which provides a secondary destination to which to log events (stderr).
For more information about logging, see Configure logs.
Use a local file server for bulk operations
To test bulk operations like IMPORT, BACKUP, or RESTORE, we recommend using a local file server.
For more details, see Use a Local File Server.
Use Docker-specific testing and development tools
When you use the cockroach start-single-node command to start a single-node cluster with Docker, some additional features are available to help with testing and development. Refer to Start a local cluster in Docker (Linux) and Start a local cluster in Docker (macOS).
See also
Was this helpful?
