> ## 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](/docs/stable/recommended-production-settings.md) 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`](/docs/stable/cockroach-start-single-node) command below starts a single-node, insecure cluster with [in-memory storage](/docs/stable/cockroach-start-single-node.md#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](/docs/stable/cluster-settings.md) and [SQL statements](/docs/stable/sql-statements.md#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](/docs/stable/online-schema-changes.md), since repeated [creation](/docs/stable/create-schema.md) and [dropping](/docs/stable/drop-schema.md) of schemas are common in automated testing.

| Setting | Value | Description |
| - | - | - |
| `kv.range_merge.queue_interval` | `50ms` | Frequent [`CREATE TABLE`](/docs/stable/create-table) or [`DROP TABLE`](/docs/stable/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](/docs/stable/show-jobs.md) 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](/docs/stable/show-jobs.md) table. For testing, the default is too fast. |
| `jobs.retention_time` | `15s` | More [schema changes](/docs/stable/online-schema-changes.md) create more [jobs](/docs/stable/show-jobs.md), 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](/docs/stable/show-statistics.md) 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`](/docs/stable/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`](/docs/stable/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 since they will lead to inaccurate results.

## Scope tests to a database when possible

It is better to scope tests to a [database](/docs/stable/create-database.md) than to a [user-defined schema](/docs/stable/create-schema.md) 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](/docs/stable/configure-logs.md#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](/docs/stable/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](/docs/stable/configure-logs.md).

## Use a local file server for bulk operations

To test bulk operations like [`BACKUP`](/docs/stable/backup) or [`RESTORE`](/docs/stable/restore), we recommend using a local file server.

For more details, see [Use a Local File Server](/docs/stable/use-a-local-file-server.md).

## 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)](/docs/stable/start-a-local-cluster-in-docker-linux.md) and [Start a local cluster in Docker (macOS)](/docs/stable/start-a-local-cluster-in-docker-mac.md).

## See also

* [Troubleshoot SQL Statements](/docs/stable/query-behavior-troubleshooting.md)
* [Optimize Statement Performance](/docs/stable/make-queries-fast.md)