How to Use CockroachDB: The Beginner's Guide (First Cluster, the Init-Once Rule, First Database, and the Kill-a-Node Lesson)

CodexFuse Team · 2026-10-31T21:52:40.522Z · 18 min read min read

Install CockroachDB v26.2, start a 3-node local cluster, initialize it exactly once, run your first SQL, and watch the cluster survive a dead node.

If your app has outgrown a single Postgres box but you are not ready to run a database team, this guide shows you how to use CockroachDB from zero: install the current v26.2 binary, start a real 3-node local cluster, initialize it exactly once, write your first SQL, watch the cluster survive a dead node, and learn the one rule that keeps beginners safe. CockroachDB is a distributed SQL database that speaks the Postgres wire protocol, replicates your data with the Raft consensus protocol, and keeps serving writes when a node dies. You do not need any distributed-systems background — if you can run commands in a terminal, you can finish this. If your first cluster will live in containers, read our Docker beginner guide first so the Docker section below feels familiar.

This is a first-use system, not a feature tour. Follow it in order: understand what it is, compare it honestly with Postgres, install it, start three nodes, init once, run SQL, open the DB Console, kill a node, then learn the secure path and the pricing. Each section opens with the direct answer, then the detail you need.

What is CockroachDB, exactly?

CockroachDB is a cloud-native, distributed SQL database that is wire-compatible with PostgreSQL, stores every range of data in triplicate across nodes, and keeps your application online when machines, racks, or whole regions fail. You talk to it like Postgres — same drivers, same SQL dialect for the everyday commands — while underneath, data is split into ranges that Raft replicates to three or more nodes, so losing a node is a normal event, not an outage. That is the whole idea in one sentence: Postgres-compatible SQL with the survival instincts of a distributed system.

Three facts set the frame for this cockroachdb tutorial. The project started in 2014 and the GitHub repository now carries over 32,000 stars; the binary ships under the CockroachDB Software License and is free to download; and the current release line is v26.2 (the v26.2.10 patch landed on Docker Hub on 2026-10-29, with the v26.2 documentation refreshed the day after). This guide targets v26.2 and says so wherever a version matters, because the aging beginner guides on page one still pin v20.2.8 from 2021.

Why learn CockroachDB when you already know Postgres?

Learn CockroachDB the moment a single database server becomes the thing you worry about at night — when you need writes to survive a dead machine without manual failover, when you plan to scale by adding servers instead of buying a bigger one, or when your users are spreading across regions. If none of that is true yet, plain Postgres is still the right answer, and this guide will not pretend otherwise.

The honest version of cockroachdb vs postgres is this: Postgres is simpler and has the bigger ecosystem; CockroachDB buys you survival and horizontal scale at the cost of running a small cluster instead of one server. Beginners often pick CockroachDB for the wrong reason (hype) — pick it for the right one: you have proven, with your own traffic or your own roadmap, that one node is not enough.

What do I need before I install CockroachDB?

You need a Linux or macOS machine with a terminal, about 2 GB of free RAM, and three free ports on localhost. That is genuinely it for the local cluster in this cockroachdb for beginners path — the community quickstart promises a working database in under ten minutes, and that holds up. The binary needs glibc, libncurses, and tzdata on Linux, which nearly every distribution ships by default.

If the cluster will eventually live on a server rather than your laptop, read what is VPS hosting to pick the right machine class first — a 3-node production-style deployment wants real cores and SSDs, not the smallest instance on the menu. For today, though, your laptop is the lab, and the lab is free.

How do I install CockroachDB?

Download the v26.2 binary archive for your platform from binaries.cockroachdb.com, extract it, and copy the cockroach binary into your PATH. The whole cockroachdb install takes under a minute — the official docs frame it as: pick your version and architecture, extract, put the binary on PATH — there is no package-manager dance required.

# Download the v26.2 archive (linux-amd64; use linux-arm64 on ARM)
curl https://binaries.cockroachdb.com/cockroach-v26.2.linux-amd64.tgz | tar -xz

# Put the binary on your PATH
sudo cp -i cockroach-v26.2.linux-amd64/cockroach /usr/local/bin/

# Prove it works
cockroach version

The cockroach version output confirms the install. If you plan to use CockroachDB's geospatial features, the docs add one step: copy the bundled C libraries into /usr/local/lib/cockroach. Skip that for this beginner arc — you will not touch spatial queries today. Prefer containers? The official Docker images are multi-platform (Intel and ARM) and the docs recommend the latest-v26.2 tag, which tracks the newest patch inside the v26.2 line; the bare latest tag is not recommended in production because it can jump major versions under you.

How do I start my first 3-node local cluster?

Run cockroach start three times with --insecure, a unique --store, --listen-addr, and --http-addr per node, and the same --join list on all three. Each node gets its own data directory and its own ports, which is how a full cockroachdb local cluster fits on one laptop.

# Node 1 — foreground first, so you can watch it wake up
cockroach start \
  --insecure \
  --store=node1 \
  --listen-addr=localhost:26257 \
  --http-addr=localhost:8080 \
  --join=localhost:26257,localhost:26258,localhost:26259

# Node 2 — new terminal, new store, new ports, same join list
cockroach start \
  --insecure \
  --store=node2 \
  --listen-addr=localhost:26258 \
  --http-addr=localhost:8081 \
  --join=localhost:26257,localhost:26258,localhost:26259 \
  --background

# Node 3 — new terminal, new store, new ports, same join list
cockroach start \
  --insecure \
  --store=node3 \
  --listen-addr=localhost:26259 \
  --http-addr=localhost:8082 \
  --join=localhost:26257,localhost:26258,localhost:26259 \
  --background

Node 1 starts in the foreground deliberately: its log lines show the cluster forming, and beginners learn more from watching one good startup than from three silent ones. Nodes 2 and 3 use --background so your terminals stay usable. Nothing is initialized yet — the nodes are gossiping, waiting for you to tell them they are a cluster. That is the next section's job, and it happens exactly once.

What does every cockroach start flag actually mean?

Every flag in the start command answers one question the node cannot guess: who am I, where do I listen, where do I keep data, and who are my friends. Learn the six below and you can read any CockroachDB deployment command ever written.

Why does cockroach init run exactly once?

Run cockroach init --insecure --host=localhost:26257 exactly once, against any one node, and never again for that cluster. The cockroachdb init command writes the cluster's identity — its genesis moment — and every node then agrees on the same cluster. Running it a second time does not "re-initialize" anything useful; on an already-initialized cluster it is rejected, and beginners who keep re-running it are usually papering over a broken first start instead of fixing it.

# One-time initialization — any node on the join list works
cockroach init --insecure --host=localhost:26257

The official docs put init as its own step for a reason: start all the nodes first, then initialize once. If a node was started with the wrong flags, fix the flags and restart the node — do not init again. This is the single most common beginner error in every community thread, which is why it gets its own section instead of a footnote.

How do I connect and run my first SQL?

Open the built-in SQL shell with cockroach sql --insecure --host=localhost:26257, then create a database, a table, and your first rows. Any node works as your SQL gateway — the docs demonstrate connecting to node 1 and node 2 and getting identical behavior, which is the first quiet proof that this is one database, not three.

# Connect to the cluster through node 1
cockroach sql --insecure --host=localhost:26257

-- Inside the SQL shell:
CREATE DATABASE bank;
USE bank;
CREATE TABLE accounts (
  id INT PRIMARY KEY,
  balance DECIMAL
);
INSERT INTO accounts VALUES (1, 1000), (2, 2500);
SELECT * FROM accounts;
-- Exit the shell any time with:
\q

That SELECT returned the same rows it would on any node, because the data lives on all three. If you know Postgres, almost everything above felt familiar — that is the wire-compatibility promise doing its job. The SQL shell also accepts the usual conveniences: \q quits, and typing a database name switches to it.

Where do I watch the cluster in the DB Console?

Open http://localhost:8080 — the DB Console on node 1 — and you will see three live nodes with an identical replica count on each, the visual proof that Raft has copied your data three ways. The Cluster Overview page is the beginner's home base: node liveness, replica balance, and the time-series dashboards for SQL queries and service latency one click away.

Three pages earn a bookmark. The Databases page shows your bank database and its tables; the Statements page ranks your queries by latency so your first slow query has a name; the Jobs page tracks long-running operations like schema changes. When the next section kills a node, this console is where you watch the cluster shrug.

What happens when I kill a node?

Send SIGTERM to one node's process, and the cluster keeps serving your SQL while the console marks the dead node "suspect" — that uninterrupted service is the entire reason distributed SQL exists. This is the lesson every tutorial describes and almost none make you perform; perform it.

# Find your three node processes
ps aux | grep cockroach

# Gracefully shut down node 3 (use its real PID)
kill -SIGTERM <node3-pid>

Now run your SELECT again in the SQL shell and refresh the DB Console. The query works; the console shows two healthy nodes and one suspect. Then restart node 3 with the exact same cockroach start command from its data directory, and watch the replica counts even out as the cluster heals. You have now done the demo that justifies the whole architecture: a database that treats a dead server as a Tuesday.

What is the 10-step beginner arc, start to finish?

The complete first session, in order — if you can do all ten, you genuinely know how to use CockroachDB at the beginner level.

1. Install the v26.2 binary and confirm it with cockroach version.
2. Start node 1 in the foreground with --insecure, a unique --store, and the shared --join list.
3. Start nodes 2 and 3 in the background with unique stores and ports.
4. Run cockroach init exactly once against any node.
5. Connect with cockroach sql and create the bank database, the accounts table, and two rows.
6. Connect through a different node and confirm the same rows — one database, three doors.
7. Open the DB Console at http://localhost:8080 and read the Cluster Overview.
8. Kill node 3 with SIGTERM, confirm SQL still works, then restart the node.
9. Stop all nodes with SIGTERM when done; restart later with the same start commands, or delete the node directories if you are finished.
10. Read the secure-path section below before this cluster ever leaves your laptop.

How do I run CockroachDB in Docker?

Create a Docker network, start three containers with the same --join list of hostnames, then init once through the first container. The cockroachdb docker flow mirrors the binary flow exactly — the only translation is that hostnames replace localhost ports, because each container is its own machine.

# One network so the nodes can find each other by name
docker network create roachnet

# Three nodes, one shared join list of hostnames
docker run -d --name=roach1 --hostname=roach1 --net=roachnet \
  -p 26257:26257 -p 8080:8080 \
  -v "roach1:/cockroach/cockroach-data" \
  cockroachdb/cockroach:v26.2.10 start --insecure --join=roach1,roach2,roach3

docker run -d --name=roach2 --hostname=roach2 --net=roachnet \
  -v "roach2:/cockroach/cockroach-data" \
  cockroachdb/cockroach:v26.2.10 start --insecure --join=roach1,roach2,roach3

docker run -d --name=roach3 --hostname=roach3 --net=roachnet \
  -v "roach3:/cockroach/cockroach-data" \
  cockroachdb/cockroach:v26.2.10 start --insecure --join=roach1,roach2,roach3

# Init once, through the first container
docker exec -it roach1 ./cockroach init --insecure

# SQL shell through the first container
docker exec -it roach1 ./cockroach sql --insecure

Two Docker-specific notes from the official docs: pin an exact patch tag like v26.2.10 (or latest-v26.2 to track patches within the line), and never use the bare latest tag for anything you care about. Named volumes keep your data alive across container restarts; deleting the volumes is the Docker equivalent of deleting the node directories.

How do I run CockroachDB on Kubernetes?

Use the official CockroachDB Kubernetes operator for anything real, and evaluate it locally on minikube before you touch a cloud cluster. The operator turns the start/init/scale dance into declarative YAML: you describe the cluster you want, and the operator converges the StatefulSets, certificates, and initialization for you.

The beginner-safe path is: install minikube, deploy the operator from the official manifests, apply a 3-node cluster manifest, then port-forward the DB Console and run the same first-SQL steps from this guide. If Kubernetes itself is new to you, our K3s beginner guide builds the cluster fundamentals this section assumes. Kubernetes is where CockroachDB's self-healing design feels most at home — dead pods get rescheduled, and the database barely notices.

When should I choose CockroachDB over single-node Postgres or an analytics database?

Choose CockroachDB when your workload is transactional (OLTP) and needs to survive failures or scale horizontally; keep single-node Postgres when the app is small and the ecosystem matters more; pick an analytics database when the workload is OLAP. The three are different tools, and beginners waste the most time using one for another's job.

The decision table:

Why must --insecure never leave my laptop?

Because --insecure disables TLS encryption and authentication entirely — anyone who can reach the port can read and write your data with no password. The official docs are blunt about it: insecure mode is for local development and testing, and running multiple nodes on one host is not a production topology. Treat the flag like a loaded demo: fine in the lab, disqualifying everywhere else.

The secure path, in one paragraph: generate a certificate authority and per-node certificates with cockroach cert create-ca, cockroach cert create-node, and cockroach cert create-client; start each node with --certs-dir and --advertise-addr instead of --insecure; open ports 26257 and 8080 between nodes; and size production nodes at 4+ vCPUs, 16 GB+ RAM, and SSD storage each, with cache and SQL memory each tuned to about 25 percent of RAM. Then disable the root user after setup. That paragraph is the whole production checklist at the beginner level — the official production checklist fills in the rest when you are ready.

How much does CockroachDB cost in 2026?

The self-hosted binary is free to download under the CockroachDB Software License; the managed cloud is usage-priced, and the old free tier is gone for new sign-ups. The cloud story changed on September 15, 2026, when Cockroach Labs launched Cockroach Continuum with two editions: Standard at $0.092 per vCPU-hour (about $203 a month for 2 vCPUs and 100 GB) and Mission Critical at $0.162 per vCPU-hour (about $1,528 a month for 12 vCPUs and 100 GB), with new organizations getting a 30-day trial carrying $400 in credit.

The fine print beginners miss: the old Basic plan's $15-a-month free credit is no longer on the cockroachdb pricing page for new organizations — existing customers keep their plans, newcomers start on the trial. For self-hosted production with support, third-party analysts put enterprise licensing in the roughly $1,500–$3,000 per core per year range with five-figure minimum commitments. For learning, none of this matters: the local cluster in this guide costs nothing.

Seven beginner mistakes to avoid

Every one of these has burned a real beginner. Read the table before you improvise.

Sources

• CockroachDB official documentation — "Deploy a Local Cluster from Binary (Insecure)", v26.2 (updated 2026-10-30): 3-node insecure start, unique --store/--listen-addr/--http-addr, shared --join list, one-time cockroach init, built-in SQL client as any-node gateway, MovR sample workload, DB Console at localhost:8080 with Raft replica view, SIGTERM node-maintenance simulation, scaling to five nodes, stopping and restarting. Fetched 2026-11-01 UTC.
• CockroachDB official documentation — "Install CockroachDB on Linux", v26.2 (updated 2026-10-30): glibc/libncurses/tzdata prerequisites, binaries.cockroachdb.com archive pattern (VERSION + ARCHITECTURE), PATH install, optional geospatial libraries at /usr/local/lib/cockroach, Docker tag guidance (latest-v26.2 recommended; latest not recommended in production), official Kubernetes operator with minikube for local evaluation, multi-platform Intel+ARM images. Fetched 2026-11-01 UTC.
• GitHub — cockroachdb/cockroach (fetched 2026-11-01 UTC): v26.2.x tag line current, v26.2.10 latest; ~32,599 stars; repository created 2014-02-06.
• Docker Hub — cockroachdb/cockroach tags (fetched 2026-11-01 UTC): v26.2.10 and latest-v26.2 tags published 2026-10-29.
• LICENSE file, cockroachdb/cockroach master (fetched 2026-11-01 UTC): ships under the CockroachDB Software License.
• Cockroach Labs — Pricing page (crawled ~4 hours before writing): Cockroach Continuum launched September 15, 2026; Standard $0.092/vCPU-hour (~$203/mo for 2 vCPU and 100 GB); Mission Critical $0.162/vCPU-hour; new organizations get a 30-day trial with $400 credit; Basic plan no longer listed for new sign-ups.
• devtoolpicks.com — "Best CockroachDB Alternatives in 2026" (33 days old): pricing-page change context, Basic-plan retirement for new sign-ups, self-hosted Enterprise Free revenue cap context. Fetched 2026-11-01 UTC.
• vendr.com — "Cockroach Labs Software Pricing and Plans 2026": self-hosted enterprise core-based licensing ranges and support-tier structure. Fetched 2026-11-01 UTC.
• copyprogramming.com — "How to Start a CockroachDB Cluster: Code Examples and 2026 Best Practices" (336 days old): secure multi-node flow (cockroach cert create-ca/create-node/create-client), --certs-dir/--advertise-addr, ports 26257/8080, 4+ vCPU / 16 GB+ RAM / SSD guidance, --cache and --max-sql-memory at 25% each, disabling root post-setup. Fetched 2026-11-01 UTC.
• mintlify.com — CockroachDB community Quick Start Guide: sub-10-minute local cluster, Linux/macOS/Windows support, 2 GB RAM minimum, distributed-transaction demo, cockroach-data cleanup. Fetched 2026-11-01 UTC.
• dzone.com — "3 Ways to Install CockroachDB — Binary, Docker, or Kubernetes" (1,940 days old): binary/Docker install patterns and --insecure/--store/--listen-addr/--http-addr/--join/--background flag explanations — the aging incumbent this guide replaces; pins v20.2.8. Fetched 2026-11-01 UTC.
• mr-oceanblue.medium.com — "Get Started with CockroachDB: A Step-by-Step Guide" (1,364 days old): step-by-step insecure cluster flow, cockroach sql client usage. Fetched 2026-11-01 UTC.

Frequently Asked Questions

Is CockroachDB free?

The self-hosted binary is free to download under the CockroachDB Software License, and everything in this guide costs nothing to run. Managed CockroachDB Cloud is usage-priced: Standard runs about $0.092 per vCPU-hour with a 30-day, $400-credit trial for new organizations, and the old free Basic plan is no longer offered to new sign-ups.

Is CockroachDB the same as Postgres?

No — it is wire-compatible with Postgres, not a Postgres fork. Your Postgres drivers, ORMs, and everyday SQL work unchanged, but the storage engine, replication, and consistency model underneath are CockroachDB's own distributed design. Treat it as Postgres-compatible, not Postgres-identical.

How many nodes does a CockroachDB cluster need?

Three nodes is the minimum for real resilience, and it is what this guide runs. Production guidance calls for at least three nodes with 4+ vCPUs, 16 GB+ RAM, and SSDs each; single-region clusters typically use 3–5 join addresses. One node works for learning SQL syntax but teaches you nothing about distributed behavior.

Can I use CockroachDB with Docker Compose or Kubernetes?

Yes to both. The Docker section above starts a 3-node cluster with plain docker run; Compose can express the same three services. For Kubernetes, use the official CockroachDB operator — evaluate it on minikube first, exactly as the official install docs suggest.

What should I learn after my first local cluster?

The secure path first: certificates, disabling --insecure, and the production checklist. After that, multi-region locality — placing data near users in different regions — is the advanced branch that justifies everything you learned here. The v26.2 docs cover both once the beginner arc is solid.