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

⚡ W skrócie · 7 min czytania

-   Architektura CockroachDB, instalacja Docker, kompatybilność z PostgreSQL, geo-partitioning, SHOW RANGES, backup (EXPORT/S3), porównanie z YugabyteDB i Vitess.
-   Architektura - jak CockroachDB rozkłada dane.
-   Pierwsze kroki - SQL kompatybilny z PostgreSQL.
-   SHOW RANGES - jak dane są rozłożone po węzłach.
-   Backup - EXPORT i S3.

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 "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 "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/)
-   [MongoDB na VPS - instalacja, konfiguracja i replica set
    
    MongoDB 7 na VPS: instalacja apt, mongod.conf (auth/TLS), użytkownicy, replica set 3 węzły, mongodump/restore backup,…
    
    ](/baza-wiedzy/mongodb-vps-instalacja/)
-   [Kubernetes StatefulSet - wdrażanie baz danych w klastrze
    
    Kubernetes StatefulSet vs Deployment, PVC templates, headless Service, wdrożenie MySQL i PostgreSQL, backup CronJob,…
    
    ](/baza-wiedzy/kubernetes-statefulset-bazy-danych/)
-   [Proxmox VE - wirtualizacja KVM i LXC dla serwerów dedykowanych
    
    Proxmox VE: instalacja, tworzenie VM i kontenerów LXC, storage ZFS/LVM/Ceph, networking bridges/VLAN, backup z Proxmox…
    
    ](/baza-wiedzy/proxmox-ve-wirtualizacja/)
-   [Jaki VPS wybrać?](/jaki-vps-wybrac/)

Autor: [Redakcja HostGrade.pl](/autorzy/) Zespół redakcyjny · Aktualizacja: 10 kwietnia 2026

Artykuły HostGrade.pl przygotowuje i aktualizuje redakcja serwisu. Ceny startowe, ceny odnowienia i warunki planów sprawdzamy w cennikach i regulaminach dostawców, a potem liczymy całkowity koszt za 2 lata (cena startowa plus odnowienia). Zasady zbierania danych i liczenia kosztów opisujemy na stronie Metodologia. Linki partnerskie oznaczamy jako #reklama.

[O redakcji i metodologii →](/autorzy/)