CockroachDB 실전 운영 가이드: 분산 SQL NewSQL 아키텍처와 프로덕션 전략

┌─────────────────────────────────────────────────────────┐
│                    SQL Layer                             │
│  (SQL 파싱, 최적화, 실행 계획, PostgreSQL 호환)          │
├─────────────────────────────────────────────────────────┤
│               Transaction Layer                          │
│  (분산 ACID 트랜잭션, MVCC, 타임스탬프 오라클)          │
├─────────────────────────────────────────────────────────┤
│               Distribution Layer                         │
│  (Range 분할, 리스홀더 선출, 메타 레인지 관리)          │
├─────────────────────────────────────────────────────────┤
│               Replication Layer                           │
│  (Raft 합의, MultiRaft, 스냅샷 전송)                    │
├─────────────────────────────────────────────────────────┤
│                Storage Layer                              │
│  (Pebble - LSM Tree 기반 키-값 스토리지 엔진)           │
└─────────────────────────────────────────────────────────┘

MultiRaft 메시지 흐름:

Node 1                    Node 2                    Node 3
┌──────────────┐          ┌──────────────┐          ┌──────────────┐
│ Range 1 (L)  │──┐       │ Range 1 (F)  │          │ Range 1 (F)  │
│ Range 5 (F)  │  │ 배치  │ Range 5 (L)  │          │ Range 5 (F)  │
│ Range 9 (F)  │  ├──────▶│ Range 9 (F)  │          │ Range 9 (L)  │
│ Range 12 (L) │──┘       │ Range 12 (F) │          │ Range 12 (F) │
└──────────────┘          └──────────────┘          └──────────────┘
(L)=Leader, (F)=Follower

# 노드 1 (AZ-a) 시작
cockroach start \
  --insecure \
  --advertise-addr=node1.example.com:26257 \
  --join=node1.example.com:26257,node2.example.com:26257,node3.example.com:26257 \
  --locality=region=ap-northeast-2,zone=az-a \
  --store=path=/data/cockroach,attrs=ssd \
  --max-offset=500ms \
  --cache=.25 \
  --max-sql-memory=.25 \
  --background

# 노드 2 (AZ-b) 시작
cockroach start \
  --insecure \
  --advertise-addr=node2.example.com:26257 \
  --join=node1.example.com:26257,node2.example.com:26257,node3.example.com:26257 \
  --locality=region=ap-northeast-2,zone=az-b \
  --store=path=/data/cockroach,attrs=ssd \
  --max-offset=500ms \
  --cache=.25 \
  --max-sql-memory=.25 \
  --background

# 노드 3 (AZ-c) 시작
cockroach start \
  --insecure \
  --advertise-addr=node3.example.com:26257 \
  --join=node1.example.com:26257,node2.example.com:26257,node3.example.com:26257 \
  --locality=region=ap-northeast-2,zone=az-c \
  --store=path=/data/cockroach,attrs=ssd \
  --max-offset=500ms \
  --cache=.25 \
  --max-sql-memory=.25 \
  --background

# 클러스터 초기화 (최초 1회)
cockroach init --insecure --host=node1.example.com:26257

# 클러스터 상태 확인
cockroach node status --insecure --host=node1.example.com:26257

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: cockroachdb
  namespace: crdb
spec:
  serviceName: cockroachdb
  replicas: 3
  selector:
    matchLabels:
      app: cockroachdb
  template:
    metadata:
      labels:
        app: cockroachdb
    spec:
      affinity:
        podAntiAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            - labelSelector:
                matchExpressions:
                  - key: app
                    operator: In
                    values:
                      - cockroachdb
              topologyKey: topology.kubernetes.io/zone
      containers:
        - name: cockroachdb
          image: cockroachdb/cockroach:v24.3.4
          ports:
            - containerPort: 26257
              name: grpc
            - containerPort: 8080
              name: http
          env:
            - name: COCKROACH_CHANNEL
              value: kubernetes-helm
          command:
            - /cockroach/cockroach
            - start
            - --advertise-addr=$(POD_NAME).cockroachdb.crdb.svc.cluster.local
            - --join=cockroachdb-0.cockroachdb.crdb.svc.cluster.local:26257,cockroachdb-1.cockroachdb.crdb.svc.cluster.local:26257,cockroachdb-2.cockroachdb.crdb.svc.cluster.local:26257
            - --locality=region=ap-northeast-2,zone=$(NODE_ZONE)
            - --cache=2GiB
            - --max-sql-memory=2GiB
            - --logtostderr=WARNING
          resources:
            requests:
              cpu: '2'
              memory: '8Gi'
            limits:
              cpu: '4'
              memory: '8Gi'
          volumeMounts:
            - name: datadir
              mountPath: /cockroach/cockroach-data
  volumeClaimTemplates:
    - metadata:
        name: datadir
      spec:
        accessModes: ['ReadWriteOnce']
        storageClassName: gp3-encrypted
        resources:
          requests:
            storage: 100Gi

-- 데이터베이스에 리전 설정
ALTER DATABASE myapp PRIMARY REGION "ap-northeast-2";
ALTER DATABASE myapp ADD REGION "us-east-1";
ALTER DATABASE myapp ADD REGION "eu-west-1";

-- 리전 장애에도 생존하도록 설정
ALTER DATABASE myapp SURVIVE REGION FAILURE;

-- 사용자 테이블: 행 단위로 리전 분산
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email STRING NOT NULL UNIQUE,
    name STRING NOT NULL,
    region crdb_internal_region NOT NULL DEFAULT 'ap-northeast-2',
    created_at TIMESTAMPTZ DEFAULT now()
) LOCALITY REGIONAL BY ROW AS region;

-- 설정 테이블: 전 리전에서 빠른 읽기 (드물게 갱신)
CREATE TABLE app_config (
    key STRING PRIMARY KEY,
    value JSONB NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT now()
) LOCALITY GLOBAL;

-- 주문 테이블: 한국 리전에 Leaseholder 고정
CREATE TABLE orders (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id),
    total_amount DECIMAL(12,2) NOT NULL,
    status STRING NOT NULL DEFAULT 'pending',
    created_at TIMESTAMPTZ DEFAULT now()
) LOCALITY REGIONAL BY TABLE IN "ap-northeast-2";

-- Follower Read: 4.8초 이전까지의 데이터를 로컬 복제본에서 읽기
SELECT * FROM users
AS OF SYSTEM TIME follower_read_timestamp()
WHERE region = 'us-east-1';

-- Bounded Staleness Read: 최소한 10초 이내의 데이터 보장
SELECT * FROM app_config
AS OF SYSTEM TIME with_max_staleness('10s');

-- 대용량 테이블에 컬럼 추가 (온라인, 무중단)
ALTER TABLE orders ADD COLUMN shipping_address STRING;

-- 인덱스 생성 (백그라운드에서 점진적으로 구축)
CREATE INDEX CONCURRENTLY idx_orders_status_created
ON orders (status, created_at DESC);

-- 스키마 변경 진행 상황 모니터링
SELECT job_id, job_type, description, status, fraction_completed
FROM [SHOW JOBS]
WHERE job_type = 'SCHEMA CHANGE'
ORDER BY created DESC
LIMIT 5;

-- Kafka로 변경 이벤트 스트리밍
CREATE CHANGEFEED FOR TABLE orders, users
INTO 'kafka://kafka-broker1:9092?topic_prefix=crdb_'
WITH
  format = 'json',
  updated,
  resolved = '10s',
  min_checkpoint_frequency = '30s',
  schema_change_policy = 'backfill',
  kafka_sink_config = '{"Flush": {"MaxMessages": 1000, "Frequency": "1s"}}';

-- Changefeed 상태 확인
SELECT job_id, description, status, error, running_status
FROM [SHOW JOBS]
WHERE job_type = 'CHANGEFEED'
ORDER BY created DESC;

-- 문제 발생 시 Changefeed 일시 중지 및 재개
PAUSE JOB (SELECT job_id FROM [SHOW JOBS] WHERE job_type = 'CHANGEFEED' AND status = 'running' LIMIT 1);
RESUME JOB <job_id>;

-- 분산 실행 계획 확인
EXPLAIN ANALYZE
SELECT o.id, o.total_amount, u.name
FROM orders o
JOIN users u ON o.user_id = u.id
WHERE o.status = 'pending'
  AND o.created_at > now() - INTERVAL '24 hours'
ORDER BY o.created_at DESC
LIMIT 50;

-- 실행 결과 예시:
-- planning time: 2ms
-- execution time: 45ms
-- distribution: full (3개 노드에서 병렬 실행)
-- vectorized: true
--
-- • limit (count: 50)
-- │ estimated row count: 50
-- │
-- └── • sort (order: created_at DESC)
--     │
--     └── • lookup join
--         │ table: users@primary
--         │ equality: (user_id) = (id)
--         │
--         └── • filter
--             │ filter: (status = 'pending') AND (created_at > ...)
--             │
--             └── • scan
--                   table: orders@idx_orders_status_created
--                   spans: [/'pending' - /'pending']

-- 클러스터 레벨 설정
SET CLUSTER SETTING kv.rangefeed.enabled = true;
SET CLUSTER SETTING kv.range_merge.queue_enabled = true;
SET CLUSTER SETTING sql.defaults.distsql = 'auto';

-- 통계 자동 수집 주기 조정 (대규모 테이블)
SET CLUSTER SETTING sql.stats.automatic_collection.min_stale_rows = 500;

-- 세션 레벨 최적화
SET vectorize = 'on';
SET distsql = 'auto';
SET reorder_joins_limit = 6;

-- 대용량 일괄 작업 시 범위 잠금 최소화
SET CLUSTER SETTING kv.bulk_io_write.max_rate = '256MiB';

-- 복합 인덱스: 쿼리 패턴에 맞게 컬럼 순서 설계
CREATE INDEX idx_orders_user_status ON orders (user_id, status)
STORING (total_amount, created_at);

-- 부분 인덱스: 활성 주문만 인덱싱하여 스토리지 절약
CREATE INDEX idx_active_orders ON orders (user_id, created_at DESC)
WHERE status IN ('pending', 'processing');

-- 역순 인덱스: 최신 데이터를 자주 조회하는 패턴
CREATE INDEX idx_orders_recent ON orders (created_at DESC)
STORING (status, total_amount);

-- 인덱스 사용 현황 확인
SELECT ti.index_name,
       ts.range_count,
       ts.approximate_disk_bytes / 1024 / 1024 AS size_mb,
       s.statistics->>'query_count' AS query_count
FROM crdb_internal.table_indexes ti
JOIN crdb_internal.index_usage_statistics s
  ON ti.index_id = s.index_id AND ti.descriptor_id = s.table_id
JOIN crdb_internal.table_span_stats ts
  ON ti.descriptor_id = ts.table_id
WHERE ti.descriptor_name = 'orders'
ORDER BY query_count DESC;

# 노드 상태 확인
cockroach node status --insecure --host=node1.example.com:26257

# 특정 노드의 로그 확인
cockroach debug zip /tmp/debug.zip --insecure --host=node1.example.com:26257

# 장애 노드 안전하게 퇴역 (복구 불가 시)
cockroach node decommission <node_id> --insecure --host=node1.example.com:26257

# 노드 간 시계 오차 확인
cockroach debug timeutil --insecure --host=node1.example.com:26257

# NTP 동기화 상태 확인
chronyc tracking
chronyc sources -v

# NTP 강제 동기화
sudo chronyc -a makestep

-- 언더레플리케이트된 레인지 확인
SELECT range_id, start_key, end_key, replicas, lease_holder
FROM crdb_internal.ranges_no_leases
WHERE array_length(replicas, 1) < 3;

-- 레플리케이션 큐 상태 확인
SELECT store_id, queue_name, process_count, process_failure_count
FROM crdb_internal.kv_store_status
WHERE queue_name = 'replicate';

# Prometheus scrape 설정
scrape_configs:
  - job_name: 'cockroachdb'
    metrics_path: '/_status/vars'
    scheme: 'http'
    static_configs:
      - targets:
          - 'node1.example.com:8080'
          - 'node2.example.com:8080'
          - 'node3.example.com:8080'
    relabel_configs:
      - source_labels: [__address__]
        target_label: instance
        regex: '(.+):8080'
        replacement: '${1}'