Autor: [Adam Nadolny](/autorzy/adam-nadolny) Ekspert DevOps i infrastruktury · Zweryfikowano Kwiecień 2026

1.  [Strona główna](/) ›
2.  [Baza wiedzy](/baza-wiedzy/) ›
3.  CockroachDB — distributed SQL

# 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

Cecha

CockroachDB

YugabyteDB

Vitess

SQL dialect

PostgreSQL

PostgreSQL + Cassandra

MySQL

Licencja

BSL (po 4 latach Apache)

Apache 2.0

Apache 2.0

Sharding

Automatyczny

Automatyczny

Manualny przez VSchema

Geo-partitioning

Tak (Enterprise)

Tak (open)

Ograniczone

Konsensus

Raft (per range)

Raft (DocDB)

MySQL replication

Złożoność

Średnia

Średnia

Wysoka

## Najczęstsze pytania

Czym jest CockroachDB i czym różni się od PostgreSQL? +

CockroachDB to rozproszona baza SQL zaprojektowana by być odporna na awarie całych węzłów lub nawet datacenter ("przeżywa jak karaluch"). Używa wire protokołu PostgreSQL, więc działa z każdym sterownikiem psycopg2, pg, node-postgres — bez modyfikacji kodu. Kluczowe różnice: CockroachDB automatycznie sharduje dane między węzłami, replikuje do 3 kopii, obsługuje multi-region i geo-partitioning. PostgreSQL to single-node, skaluje pionowo lub przez Citus/sharding ręczny. CockroachDB ma wyższe latencje dla prostych zapytań (rozproszony konsensus), ale skaluje poziomo bez ograniczeń. Jest droższe w obsłudze i zasobach na małą skalę — dla projektów jednowęzłowych PostgreSQL jest lepszy.

Czy CockroachDB jest rzeczywiście kompatybilny z PostgreSQL? +

CockroachDB jest kompatybilny z PostgreSQL na poziomie protokołu i dużej części składni SQL. Działają: SELECT/INSERT/UPDATE/DELETE, JOIN, subqueries, window functions, CTE (WITH), transactions, sequences, types (INT, TEXT, DECIMAL, JSONB, ARRAY), funkcje agregujące. Nie działają lub są różne: niektóre typy danych (np. XML), PL/pgSQL, triggers, niektóre systemowe tabele pg\_catalog, pg\_dump/pg\_restore wymagają specjalnego podejścia, COPY FROM STDIN jest zaimplementowane ale z ograniczeniami. W praktyce: Prisma ORM, GORM, sqlalchemy, Django ORM, node-postgres działają dobrze. Surowy SQL migrowany ze starszego kodu może wymagać kilku poprawek.

Kiedy CockroachDB, a kiedy YugabyteDB lub Vitess? +

CockroachDB: najlepszy jeśli zależy Ci na odporności na split-brain i disaster recovery między datacenter, potrzebujesz PostgreSQL-compatible SQL z automatycznym shardingiem, budujesz aplikację globalną gdzie dane muszą być blisko użytkownika (geo-partitioning). YugabyteDB: podobny do CockroachDB, jest open-source bez ograniczeń licencji, obsługuje zarówno PostgreSQL (YSQL) jak i Cassandra (YCQL) API, ma nieco inną architekturę (DocDB storage). Vitess: sharding MySQL (nie PostgreSQL), stworzony przez YouTube dla bardzo dużego ruchu, wymaga własnej warstwy routingu (VTGate), bardziej złożony w konfiguracji. Dla startupu z małym ruchem — PostgreSQL. Dla globalnej aplikacji z milionami użytkowników — CockroachDB lub YugabyteDB.

## Sprawdź oferty pasujące do tego scenariusza

Poniżej masz szybkie przejścia do ofert i stron z kodami rabatowymi tam, gdzie są dostępne.

Contabo

VPS z NVMe dla CockroachDB — szybki I/O dla rozproszonego storage

NVMe VPS

[Aktywuj rabat →](/out/contabo)

#Reklama · link partnerski

[Zobacz kod rabatowy →](/kody-rabatowe/contabo)

ProSerwer.pl

Polski VPS dla CockroachDB — niska latencja w sieci lokalnej

Polski VPS

[Aktywuj rabat →](/out/proserwer-pl)

#Reklama · link partnerski

[Zobacz kod rabatowy →](/kody-rabatowe/proserwer)

## Powiązane strony

-   [PostgreSQL na VPS — instalacja i konfiguracja](/baza-wiedzy/postgresql-vps-instalacja-konfiguracja)
-   [PostgreSQL Streaming Replication](/baza-wiedzy/postgresql-replikacja-streaming)
-   [Docker Compose w produkcji](/baza-wiedzy/docker-compose-produkcja)
-   [Wszystkie artykuły](/baza-wiedzy/)