CockroachDB — distributed SQL: PostgreSQL-compatible skalowalna baza

Opublikowano: 10 kwietnia 2026 · Kategoria: VPS / Bazy danych

CockroachDB to rozproszona baza SQL zaprojektowana pod hasłem "survive anything" — przeżywa awarie węzłów, datacenter, a nawet całych regionów. Nazwa pochodzi od karalucha, który przeżywa warunki trudne dla innych stworzeń. Używa protokołu PostgreSQL, więc istniejące sterowniki (psycopg2, node-postgres, prisma) działają bez zmian kodu. Pod spodem dane są automatycznie shardowane i replikowane między węzłami. Ten artykuł opisuje architekturę, instalację, podstawy pracy z CockroachDB i kiedy warto go wybrać zamiast PostgreSQL.

Architektura — jak CockroachDB rozkłada dane

Dane w CockroachDB są podzielone na Ranges (domyślnie 128 MB każdy). Każdy Range jest replikowany do 3 węzłów przez protokół Raft. Warstwa SQL tłumaczy zapytania SQL na operacje na key-value storage (RocksDB pod spodem). Każdy węzeł może obsługiwać zapytania — nie ma single point of failure. Automatyczny sharding przenosi Ranges między węzłami gdy dodajesz nowe serwery.

# === Instalacja przez Docker Compose (klaster 3-węzłowy) ===

# docker-compose.yml
# version: '3.8'
# services:
#   roach1:
#     image: cockroachdb/cockroach:latest
#     command: start --insecure --join=roach1,roach2,roach3 --advertise-addr=roach1
#     ports:
#       - "26257:26257"  # SQL
#       - "8080:8080"    # Admin UI
#     volumes:
#       - roach1-data:/cockroach/cockroach-data
#   roach2:
#     image: cockroachdb/cockroach:latest
#     command: start --insecure --join=roach1,roach2,roach3 --advertise-addr=roach2
#   roach3:
#     image: cockroachdb/cockroach:latest
#     command: start --insecure --join=roach1,roach2,roach3 --advertise-addr=roach3

docker-compose up -d

# Inicjalizacja klastra (jednorazowo)
docker exec roach1 cockroach init --insecure

# Sprawdz status
docker exec roach1 cockroach node status --insecure
# ID | Address | Status | replicas_leaders | replicas_followers

# Admin UI: http://localhost:8080
# Powiadamia o replikacji, Ranges, latencji zapytan

Pierwsze kroki — SQL kompatybilny z PostgreSQL

# Polaczenie przez cockroach sql lub psql
docker exec -it roach1 cockroach sql --insecure

# Lub przez psql (standardowy klient PostgreSQL)
psql -h localhost -p 26257 -U root -d defaultdb

-- SQL jest kompatybilny z PostgreSQL!
CREATE DATABASE myapp;
USE myapp;

-- Tworzenie tabeli (sk ladnia PostgreSQL)
CREATE TABLE orders (
    id          UUID DEFAULT gen_random_uuid() PRIMARY KEY,
    customer_id INT NOT NULL,
    amount      DECIMAL(10, 2) NOT NULL,
    status      STRING NOT NULL DEFAULT 'pending',
    region      STRING NOT NULL DEFAULT 'eu-west',
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),

    INDEX idx_customer (customer_id),
    INDEX idx_status_region (status, region)
);

-- INSERT dziala tak samo jak w PostgreSQL
INSERT INTO orders (customer_id, amount, status)
VALUES (1001, 299.99, 'pending'), (1002, 149.50, 'completed');

-- SELECT, JOIN, CTEs - wszystko dziala
SELECT
    customer_id,
    COUNT(*) AS order_count,
    SUM(amount) AS total
FROM orders
WHERE created_at >= now() - INTERVAL '30 days'
GROUP BY customer_id
HAVING SUM(amount) > 100
ORDER BY total DESC;

-- Transakcje ACID
BEGIN;
UPDATE orders SET status = 'shipped' WHERE id = '...';
INSERT INTO shipping_log (order_id, event) VALUES ('...', 'dispatched');
COMMIT;

SHOW RANGES — jak dane są rozłożone po węzłach

-- Sprawdz jak tabela jest podzielona na Ranges
SHOW RANGES FROM TABLE orders;
-- start_key | end_key | range_id | replicas | lease_holder

-- Statystyki klastra
SHOW CLUSTER SETTING kv.range_merge.queue_enabled;

-- Geo-partitioning: dane EU w EU, USA w USA
ALTER TABLE orders PARTITION BY LIST (region) (
    PARTITION eu VALUES IN ('eu-west', 'eu-central'),
    PARTITION us VALUES IN ('us-east', 'us-west')
);

-- Przypnij partycje do konkretnych datacenter (Enterprise)
-- ALTER PARTITION eu OF TABLE orders CONFIGURE ZONE USING
--   constraints = '[+region=eu-west-1]';

-- Sprawdz rozklad po wezlach (ktory node ma lease)
SELECT range_id, lease_holder, replicas
FROM crdb_internal.ranges
WHERE table_name = 'orders'
LIMIT 10;

Backup — EXPORT i S3

-- Backup do katalogu lokalnego (wersja free)
BACKUP DATABASE myapp INTO 'nodelocal://1/backup/myapp-$(date)';

-- Backup do S3 (lub kompatybilnego: MinIO, Backblaze)
BACKUP DATABASE myapp
INTO 's3://my-bucket/cockroach-backups?AWS_ACCESS_KEY_ID=...&AWS_SECRET_ACCESS_KEY=...';

-- Full + incremental backup
BACKUP DATABASE myapp
INTO LATEST IN 's3://my-bucket/cockroach-backups?...';

-- Restore
RESTORE DATABASE myapp
FROM 's3://my-bucket/cockroach-backups/2026/04/10/?...';

-- Sprawdz backupy
SHOW BACKUPS IN 's3://my-bucket/cockroach-backups?...';

-- Alternatywa: pg_dump (przez psql, wolniejsze ale standard)
pg_dump -h localhost -p 26257 -U root myapp > /backup/myapp.sql

Porównanie distributed SQL

Najczęstsze pytania