How to Install CockroachDB Using Docker

May 06, 2025

CockroachDB is a powerful, distributed SQL database that's designed for high availability and horizontal scalability. It’s popular for modern cloud-native apps that require strong consistency, fault tolerance, and easy scaling.
If you’re just getting started and want to try CockroachDB locally without installing anything directly on your system, Docker is the fastest way to do it.
In this article, you’ll learn how to install and run CockroachDB using Docker, step by step. We’ll walk through pulling the image, running the container, and connecting to the database using its built-in SQL shell and admin UI.

Why Use Docker for CockroachDB?

Docker makes it incredibly simple to get a database up and running without cluttering your system. Here’s why it’s a great option:

No installation required on your OS
Easy to remove when done
Perfect for development and local testing
Same environment across all systems

Prerequisites

Before we begin, ensure that Docker is installed on your system.

For macOS/Windows:

Install Docker Desktop from:
👉 https://www.docker.com/products/docker-desktop

For Ubuntu/Linux:

sudo apt update && sudo apt install docker.io

Confirm it’s working:

docker --version

Step 1: Pull the CockroachDB Docker Image

Cockroach Labs maintains an official Docker image on Docker Hub.
To download the latest image:

docker pull cockroachdb/cockroach

You can also pull a specific version, like:

docker pull cockroachdb/cockroach:v23.1.11

Step 2: Run a Single-Node CockroachDB Container

Let’s start a single-node instance of CockroachDB, which is perfect for development.

docker run -d --name cockroach-single \
  -p 26257:26257 -p 8080:8080 \
  cockroachdb/cockroach start-single-node \
  --insecure

Explanation:

--name cockroach-single: Names the container
-p 26257:26257: Maps the SQL port (default)
-p 8080:8080: Maps the Admin UI port
start-single-node: Runs CockroachDB in single-node mode
--insecure: Enables HTTP and disables encryption (for dev only)

Use --insecure only in development environments. For production, always use secure mode with certificates.

Step 3: Access the Admin UI

CockroachDB includes a web-based Admin UI for monitoring and debugging.
Open your browser and go to:

http://localhost:8080

You’ll see stats like:

Node status
SQL activity
Storage usage
Query performance

Step 4: Connect Using the Built-in SQL Client

To interact with your CockroachDB container, use the SQL shell:

docker exec -it cockroach-single ./cockroach sql --insecure

This command opens the SQL CLI inside the container.
Try running:

SHOW DATABASES;

Or create a new database:

CREATE DATABASE testdb;

Step 5: Use Volumes to Persist Data (Optional)

By default, Docker containers are ephemeral—if you delete the container, your data is gone. Use volumes to persist CockroachDB data:

docker volume create cockroach-data

Then run the container with volume mounting:

docker run -d --name cockroach-single \
  -p 26257:26257 -p 8080:8080 \
  -v cockroach-data:/cockroach/cockroach-data \
  cockroachdb/cockroach start-single-node \
  --insecure

This way, your data survives container restarts.

Step 6: Useful Docker Commands

Task	Command
Stop the container	`docker stop cockroach-single`
Start the container	`docker start cockroach-single`
Remove the container	`docker rm -f cockroach-single`
Remove the volume	`docker volume rm cockroach-data`
View logs	`docker logs cockroach-single`

Initialize SQL Schema

After creating your database, you can create tables like this:

USE testdb;

CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  username STRING NOT NULL,
  email STRING UNIQUE NOT NULL
);

Then insert some sample data:

INSERT INTO users (username, email) VALUES ('alice', 'alice@example.com');

And fetch it:

SELECT * FROM users;

Best Practices

Always use volumes to persist data in development
Use --secure with certificates in production
Avoid exposing ports in public environments unless secured
Use the Admin UI to monitor database performance