I. Overview

Enough theory — let's get our hands dirty. In this part, we'll set up CockroachDB locally using Docker, connect to it with a standard PostgreSQL client, and run some basic SQL to get a feel for how it works.

II. Local Setup with Docker

The fastest way to get started is with Docker. You don't need to install anything on your machine directly.

Prerequisites: Docker installed and running.

Step 1 — Pull the CockroachDB image:

docker pull cockroachdb/cockroach:latest

Step 2 — Create a Docker network:

docker network create -d bridge roachnet

Step 3 — Start 3 nodes (simulating a real cluster):

1# Node 1
2docker run -d \
3  --name=roach1 \
4  --hostname=roach1 \
5  --net=roachnet \
6  -p 26257:26257 -p 8080:8080 \
7  cockroachdb/cockroach:latest start \
8  --insecure \
9  --join=roach1,roach2,roach3
10
11# Node 2
12docker run -d \
13  --name=roach2 \
14  --hostname=roach2 \
15  --net=roachnet \
16  cockroachdb/cockroach:latest start \
17  --insecure \
18  --join=roach1,roach2,roach3
19
20# Node 3
21docker run -d \
22  --name=roach3 \
23  --hostname=roach3 \
24  --net=roachnet \
25  cockroachdb/cockroach:latest start \
26  --insecure \
27  --join=roach1,roach2,roach3

Step 4 — Initialize the cluster:

docker exec -it roach1 ./cockroach init --insecure

Step 5 — Verify the cluster is running:

docker exec -it roach1 ./cockroach node status --insecure

You should see 3 nodes all with is_available: true.

💡 Tip: For quick testing, spin up a single-node cluster:

`bash

docker run -d --name=roach-single -p 26257:26257 -p 8080:8080 \

cockroachdb/cockroach:latest start-single-node --insecure

`

III. CockroachDB Cloud (Free Tier — No Docker Needed)

Don't want to run Docker? CockroachDB Cloud offers a free serverless tier — no credit card required.

1. Go to cockroachlabs.cloud

2. Sign up and create a new Serverless cluster

3. Download the connection string — it looks like:
javascript

postgresql://username:password@free-tier.gcp-us-central1.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full

The free tier gives you 10 GiB storage and 50M RUs/month — more than enough to learn and experiment.

IV. Connect with a PostgreSQL Client

CockroachDB speaks the PostgreSQL wire protocol, so any PostgreSQL client works out of the box.

Using the built-in SQL shell:

1# Docker local cluster
2docker exec -it roach1 ./cockroach sql --insecure
3
4# CockroachDB Cloud
5cockroach sql --url="postgresql://..."

Using psql:

psql "postgresql://root@localhost:26257/defaultdb?sslmode=disable"

Using any PostgreSQL GUI (TablePlus, DBeaver, DataGrip) — point it to localhost:26257, username root, no password (insecure mode).

V. Basic SQL Operations

Once connected, let's create a database and run some queries.

Create a database and table:

1CREATE DATABASE demo;
2USE demo;
3
4CREATE TABLE users (
5    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
6    name STRING NOT NULL,
7    email STRING UNIQUE NOT NULL,
8    created_at TIMESTAMPTZ DEFAULT now()
9);

Insert some data:

1INSERT INTO users (name, email) VALUES
2    ('Alice', 'alice@example.com'),
3    ('Bob', 'bob@example.com'),
4    ('Charlie', 'charlie@example.com');

Query the data:

SELECT * FROM users ORDER BY created_at DESC;

Check range distribution (CockroachDB-specific):

SHOW RANGES FROM TABLE users;

This shows you exactly how your data is distributed across nodes — something you can't do in regular PostgreSQL.

VI. The Admin UI

CockroachDB comes with a built-in dashboard. Open your browser at:

http://localhost:8080

Here you can see:

• Node status — which nodes are up/down

• SQL metrics — QPS, latency, error rates

• Range distribution — how data is spread across the cluster

• Active queries — what's currently running

This is incredibly useful for understanding your cluster's health without any external monitoring setup.

VII. Conclusion

In just a few commands, you have a fully functional 3-node distributed SQL cluster running locally. Notice how everything behaves exactly like PostgreSQL — the same SQL syntax, the same client tools — but with distributed superpowers underneath.

In Part 4, we'll explore one of the most powerful aspects of CockroachDB: transactions and serializable isolation.

Thank you for reading! 😊