What is CockroachDB

CockroachDB is a SQL Database

What Problem it solves?
Traditional relational databases (e.g. PostgreSQL, MySQL) are strong on SQL and ACID transactions but are hard to scale horizontally and do not survive datacenter failures without significant operational overhead. NoSQL databases (e.g. Cassandra, DynamoDB) scale well but sacrifice ACID transactions and familiar SQL semantics. CockroachDB is designed to give you both:
  Horizontal scalability(Add nodes to grow storage and throughput linearly)
  Survivability(Tolerates disk, node, rack, and datacenter failures automatically)

When to choose CockroachDB
- Applications that need PostgreSQL semantics at scale (multi-region, high availability)
- Systems where zero-downtime rolling upgrades are mandatory
- Workloads requiring strong ACID guarantees that span multiple rows/tables
- Scenarios where geo-partitioning or locality-aware placement is needed

Architecture

                 Application
                     |   /\
                     \/   |
<----------------CockroachDB Cluster-------------------------------------------->

--AWSRegion:Mumbai. AZ-1-     --AWSRegion:NYC. AZ-2-     --AWSRegion:Japan. AZ-3-
| EC2(CockroachDB node)|    | EC2(CockroachDB node) |    |EC2(CockroachDB node) |
------------------------       ---------------------      ------------------------
      

@startuml
title CockroachDB Distributed SQL Architecture Example

actor User as u
participant "SQL Layer" as sl
participant "KV Client \n DistSender layer" as sda
box Distributed Monolithic KV Store
participant "AZ1\n\nnode1\nPebble" as n1
participant "AZ2\n\nnode2\nPebble" as n2
participant "AZn\n\nnoden\nPebble" as nn
end box 

note over n2
Pebble is Go-native LSM-tree engine store
CockroachDB uses it store data underhood
end note

note over n1
This is huge distributed store
end note


note over u
CREATE TABLE users(
id INT PRIMARY KEY,
name STRING);

INSERT INTO users(name) 
VALUE('Alice');

Already Completed
end note

u -> sl: SELECT name FROM\nusers WHERE id=1
note over sl
Convert to
KV type query
end note

sl->sda: SELECT name FROM\nusers WHERE id=1
sda -> n1:Get row with \nkey:user/1

note over n1
key user/10
mapped to 
range/0,100
end note
@enduml
            

Build & Run CockroachDB from source

Build from source

curl -Lo /tmp/bazelisk \
  https://github.com/bazelbuild/bazelisk/releases/latest/download/bazelisk-linux-amd64
chmod +x /tmp/bazelisk
sudo mv /tmp/bazelisk /usr/local/bin/bazel
bazel version
dpkg -l ccache 2>/dev/null | grep -q "^ii" && sudo apt remove --purge ccache -y || echo "ccache not installed, OK"

# ── Step 3: Install crlfmt (Go code formatter used by CockroachDB) ──────────
go install github.com/cockroachdb/crlfmt@latest

# ── Step 4: Run the environment doctor ──────────────────────────────────────
# dev doctor checks Go version, Bazelisk, and other prerequisites and tells you
# exactly what is missing. Fix anything it reports before building.
cd ~/cockroach
./dev doctor

# ── Step 5: Build the binary ────────────────────────────────────────────────
# "short" builds cockroach without the web UI — much faster, good for backend work.
# Output: ./cockroach and ./cockroach-short in the repo root.
./dev build short
      

Run Cockroachdb

# ── Foreground (logs print to terminal + log files) ──────
# Print WARNING+ to stderr (default — minimal noise)
./cockroach start-single-node --insecure --listen-addr=localhost:26257 --logtostderr=WARNING

# Print INFO+ to stderr (recommended during development)  ****DO THIS****
./cockroach start-single-node --insecure --listen-addr=localhost:26257--logtostderr=INFO

# ── Background (returns immediately; logs only go to files) ──────────────────
./cockroach start-single-node --insecure --listen-addr=localhost:26257 --background

# ── Foreground with all INFO logs also printed to stderr ─────────────────────
# Best option for development: you see everything as it happens in the terminal.
./cockroach start-single-node --insecure --listen-addr=localhost:26257 \
  --logtostderr=INFO
      

Log Files

CockroachDB splits logs across multiple files by **log channel**. All files are in `cockroach-data/logs/`.

# Follow the main log (startup messages, node events, errors)
tail -f cockroach-data/logs/cockroach.log

| File (symlink) | Channel | What it contains |
|---|---|---|
| `cockroach.log` | DEV + OPS | Main server log — startup, node events, most errors |
| `cockroach-health.log` | HEALTH | Periodic health samples, liveness heartbeats |
| `cockroach-pebble.log` | STORAGE | Pebble (storage engine) internal events |
| `cockroach-kv-exec.log` | KV_EXEC | KV-layer execution events |
| `cockroach-kv-distribution.log` | KV_DISTRIBUTION | Range leases, rebalancing, Raft |
| `cockroach-sql-schema.log` | SQL_SCHEMA | DDL events (CREATE TABLE, ALTER TABLE, etc.) |
| `cockroach-stderr.log` | — | Anything written to stderr |
      

Doing code change

// Add log line 
pkg/cli/cli.go
	ctx := context.Background()
	log.Ops.Shoutf(ctx, severity.INFO, "Amit cli::Main()")

// Rebuild
./dev build short

// Start again
./cockroach start-single-node --insecure --listen-addr=localhost:26257 --logtostderr=INFO
      

Code walk

cli.Main()  //pkg/cmd/cockroach/main.go
  doMain()  //pkg/cli/cli.go
    Run() 
      runStart() //pkg/cli/start.go
        runStartInternal()  //pkg/cli/start.go