Test Your Application Locally

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 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 command below starts a single-node, insecure cluster with . 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 and for improved performance during functional unit testing and continuous integration testing. In particular, some of these settings will increase the performance of , since repeated and of schemas are common in automated testing.

Setting	Value	Description
kv.range_merge.queue_interval	50ms	Frequent or 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 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 table. For testing, the default is too fast.
jobs.retention_time	15s	More create more , 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 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 DATABASE system CONFIGURE ZONE USING "gc.ttlseconds"	600	Faster jobs table cleanup. For more information, see .

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 than to a 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 . 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 :

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 .

Use a local file server for bulk operations

To test bulk operations like or , we recommend using a local file server.

For more details, see .

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

See also