> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 [Production Checklist](https://docs.cockroachlabs.com/docs/v24.2/recommended-production-settings) for information about preparing your cluster for production.

> [!CAUTION]
>
> 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`](https://docs.cockroachlabs.com/docs/v24.2/cockroach-start-single-node) command below starts a single-node, insecure cluster with [in-memory storage](https://docs.cockroachlabs.com/docs/v24.2/cockroach-start-single-node#store). Using in-memory storage improves the speed of the cluster for local testing purposes.

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
cockroach start-single-node --insecure --store=type=mem,size=0.25 --advertise-addr=localhost
```

We recommend the following additional [cluster settings](https://docs.cockroachlabs.com/docs/v24.2/cluster-settings) and [SQL statements](https://docs.cockroachlabs.com/docs/v24.2/sql-statements#data-definition-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](https://docs.cockroachlabs.com/docs/v24.2/online-schema-changes), since repeated [creation](https://docs.cockroachlabs.com/docs/v24.2/create-schema) and [dropping](https://docs.cockroachlabs.com/docs/v24.2/drop-schema) of schemas are common in automated testing.

| Setting | Value | Description |
| - | - | - |
| `kv.range_merge.queue_interval` | `50ms` | Frequent [`CREATE TABLE`](https://docs.cockroachlabs.com/docs/v24.2/create-table) or [`DROP TABLE`](https://docs.cockroachlabs.com/docs/v24.2/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](https://docs.cockroachlabs.com/docs/v24.2/show-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](https://docs.cockroachlabs.com/docs/v24.2/show-jobs) table. For testing, the default is too fast. |
| `jobs.retention_time` | `15s` | More [schema changes](https://docs.cockroachlabs.com/docs/v24.2/online-schema-changes) create more [jobs](https://docs.cockroachlabs.com/docs/v24.2/show-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](https://docs.cockroachlabs.com/docs/v24.2/show-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 ... CONFIGURE ZONE`](https://docs.cockroachlabs.com/docs/v24.2/alter-range#configure-zone). |
| `ALTER DATABASE system CONFIGURE ZONE USING "gc.ttlseconds"` | `600` | Faster jobs table cleanup. For more information, see [`ALTER DATABASE ... CONFIGURE ZONE`](https://docs.cockroachlabs.com/docs/v24.2/alter-database#configure-zone). |

To change all of the settings described above at once, run the following SQL statements:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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;
```

> [!CAUTION]
>
> These settings **are not** recommended for [performance benchmarking of CockroachDB](https://docs.cockroachlabs.com/docs/v24.2/performance-benchmarking-with-tpcc-local) since they will lead to inaccurate results.

## Scope tests to a database when possible

It is better to scope tests to a [database](https://docs.cockroachlabs.com/docs/v24.2/create-database) than to a [user-defined schema](https://docs.cockroachlabs.com/docs/v24.2/create-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](https://docs.cockroachlabs.com/docs/v24.2/configure-logs#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](https://docs.cockroachlabs.com/docs/v24.2/cockroach-start-single-node#logging):

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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](https://docs.cockroachlabs.com/docs/v24.2/configure-logs).

## Use a local file server for bulk operations

To test bulk operations like [`BACKUP`](https://docs.cockroachlabs.com/docs/v24.2/backup) or [`RESTORE`](https://docs.cockroachlabs.com/docs/v24.2/restore), we recommend using a local file server.

For more details, see [Use a Local File Server](https://docs.cockroachlabs.com/docs/v24.2/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](https://docs.cockroachlabs.com/docs/v24.2/start-a-local-cluster-in-docker).

## See also

* [Troubleshoot SQL Statements](https://docs.cockroachlabs.com/docs/v24.2/query-behavior-troubleshooting)
* [Optimize Statement Performance](https://docs.cockroachlabs.com/docs/v24.2/make-queries-fast)
