# Citus

Citus는 PostgreSQL을 기반으로 하는 오픈 소스 분산 데이터베이스 확장 프로그램으로, 단일 서버의 성능 한계를 넘어 데이터를 여러 노드에 분산 저장하고 쿼리를 병렬로 처리함으로써 수평적 확장성(Horizontal Scalability)을 제공하는 솔루션입니다.

## 1. 개요
Citus는 표준 PostgreSQL의 기능을 그대로 유지하면서, 대규모 데이터셋을 처리하기 위해 설계되었습니다. 일반적인 관계형 데이터베이스(RDBMS)가 서버의 사양을 높이는 수직적 확장(Scale-up)에 의존하는 것과 달리, Citus는 여러 대의 저렴한 서버를 추가하여 성능을 높이는 수평적 확장(Scale-out)을 가능하게 합니다. 이를 통해 테라바이트(TB) 단위 이상의 대규모 데이터 처리와 초당 수만 건의 트랜잭션을 처리하는 고성능 분석 및 트랜잭션 환경을 구축할 수 있습니다.

## 2. 동작 원리 및 아키텍처
Citus는 클러스터 구조를 통해 동작하며, 크게 **코디네이터(Coordinator)** 노드와 **워커(Worker)** 노드로 역할이 나뉩니다.

### 2.1 노드 역할 분담
*   **코디네이터 노드**: 클라이언트의 요청을 받는 진입점입니다. 메타데이터(테이블 구조, 샤드 위치 등)를 관리하며, 들어온 쿼리를 분석하여 어떤 워커 노드로 보낼지 결정하고 결과를 취합하여 반환합니다.
*   **워커 노드**: 실제 데이터가 저장되는 곳입니다. 코디네이터로부터 전달받은 쿼리를 자신의 로컬 데이터(샤드)에 대해 실행하고 그 결과를 코디네이터로 전송합니다.

| 구분 | 코디네이터 (Coordinator) | 워커 (Worker) |
| :--- | :--- | :--- |
| **주요 역할** | 쿼리 라우팅, 메타데이터 관리, 결과 취합 | 데이터 저장, 로컬 쿼리 실행 |
| **데이터 저장** | 메타데이터 및 로컬 테이블 저장 | 분산 테이블의 샤드(Shard) 저장 |
| **클라이언트 연결** | 직접 연결됨 | 일반적으로 코디네이터를 통해 연결 |
| **핵심 기능** | 쿼리 계획(Query Planning) 및 분산 | 병렬 데이터 처리 |

### 2.2 샤딩(Sharding) 메커니즘
샤딩이란 거대한 테이블을 작은 단위의 **샤드(Shard)**로 쪼개어 여러 노드에 분산 배치하는 기술입니다. Citus는 해시 기반 샤딩을 사용하여, 특정 컬럼(샤드 키)의 값을 해싱하여 데이터가 저장될 워커 노드를 결정합니다. 이를 통해 데이터가 특정 노드에 쏠리지 않고 균등하게 분산되도록 보장합니다.

## 3. 핵심 기능

### 3.1 분산 테이블과 참조 테이블
Citus는 데이터의 성격에 따라 두 가지 테이블 타입을 제공합니다.

*   **분산 테이블 (Distributed Tables)**: 샤드 키를 기준으로 여러 워커 노드에 나누어 저장되는 테이블입니다. 대용량 로그, 트랜잭션 내역 등 데이터 양이 많은 테이블에 사용합니다.
*   **참조 테이블 (Reference Tables)**: 모든 워커 노드에 동일하게 복제되어 저장되는 테이블입니다. 코드 테이블, 설정 값 등 크기가 작고 조인(Join) 작업이 빈번한 테이블에 사용하며, 분산 테이블과의 로컬 조인을 가능하게 하여 네트워크 오버헤드를 줄입니다.

| 구분 | 분산 테이블 (Distributed Table) | 참조 테이블 (Reference Table) |
| :--- | :--- | :--- |
| **데이터 저장 방식** | 샤드 키 기반으로 여러 노드에 분산 저장 | 모든 워커 노드에 전체 복제 저장 |
| **주요 용도** | 대규모 팩트 테이블, 로그, 트랜잭션 데이터 | 마스터 데이터, 설정 값, 코드 테이블 |
| **확장성** | 노드 추가 시 데이터 분산 가능 (Scale-out) | 데이터 크기가 작아야 함 (복제 비용 발생) |
| **조인 특성** | 동일 샤드 키 사용 시 로컬 조인 가능 | 모든 분산 테이블과 로컬 조인 가능 |

### 3.2 쿼리 병렬 실행 (Parallel Query Execution)
코디네이터는 쿼리를 분석하여 여러 워커 노드에서 동시에 실행될 수 있도록 분산합니다. 예를 들어, 전체 매출 합계를 구하는 쿼리가 들어오면 각 워커 노드가 자신이 가진 샤드에서 부분 합계를 계산하고, 코디네이터가 이를 최종 합산하는 방식으로 처리 시간을 획기적으로 단축합니다.

## 4. 설치 및 기본 설정

### 4.1 설치 과정
Citus는 PostgreSQL의 확장 프로그램(Extension) 형태로 설치됩니다. OS 패키지 매니저를 통해 `citus` 패키지를 설치한 후, `postgresql.conf` 파일의 `shared_preload_libraries` 설정에 `citus`를 추가해야 합니다.

### 4.2 클러스터 구성 예시
설치 후 데이터베이스에 접속하여 다음과 같은 SQL 명령어로 Citus를 활성화하고 노드를 구성합니다. **주의: `citus_add_node`를 호출하기 전, 모든 워커 노드에도 `citus` 확장 프로그램이 설치되어 있어야 합니다.**

```sql
-- 1. 코디네이터 및 모든 워커 노드에서 Citus 확장 프로그램 활성화
CREATE EXTENSION citus;

-- 2. 워커 노드 추가 (IP와 포트 지정)
-- 워커 노드들이 이미 실행 중이며 citus 확장이 설치된 상태여야 합니다.
SELECT citus_add_node('worker-node-1', 5432);
SELECT citus_add_node('worker-node-2', 5432);

-- 3. 테이블 생성 및 분산 설정
CREATE TABLE users (
    user_id int PRIMARY KEY,
    user_name text,
    created_at timestamp
);

-- user_id를 샤드 키로 하여 테이블을 분산함
SELECT citus_create_distributed_table('users', 'user_id');
```

## 5. 활용 사례 및 최적화 전략

### 5.1 주요 유스케이스
*   **멀티 테넌트(Multi-tenant) 애플리케이션**: 고객사(Tenant)별로 데이터를 격리하여 저장하는 SaaS 서비스에 최적입니다. `tenant_id`를 샤드 키로 설정하면 특정 고객의 모든 데이터가 동일한 노드에 저장되어 매우 빠른 쿼리 성능을 보입니다.
*   **실시간 분석 (Real-time Analytics)**: 대규모 시계열 데이터나 이벤트 로그를 저장하고, 이를 병렬 쿼리로 빠르게 집계 분석하는 대시보드 서비스에 적합합니다.

### 5.2 샤드 키(Shard Key) 선정 기준
샤드 키 선정은 Citus 성능의 핵심입니다. 잘못된 키 선정은 '데이터 쏠림(Skew)' 현상이나 '네트워크 셔플링(Network Shuffling, 노드 간 데이터 이동으로 인한 성능 저하)'을 유발합니다.

*   **선정 기준 예시**:
    *   **조인 빈도가 높은 컬럼**: 자주 함께 조인되는 테이블들은 동일한 샤드 키를 가져야 워커 노드 내부에서 '로컬 조인'이 일어나 성능이 극대화됩니다. (예: `orders` 테이블과 `order_items` 테이블 모두 `order_id`를 키로 설정)
    *   **데이터 분포가 균등한 컬럼**: 특정 값에 데이터가 몰리지 않는 고유성이 높은 컬럼을 선택해야 합니다. (예: `status` 같은 낮은 카디널리티 컬럼보다는 `user_id` 같은 높은 카디널리티 컬럼 선택)
    *   **필터링 조건으로 자주 쓰이는 컬럼**: `WHERE` 절에 항상 포함되는 컬럼을 키로 잡으면 코디네이터가 쿼리를 특정 노드로만 보내는 '샤드 프루닝(Shard Pruning, 불필요한 샤드 제외)'이 가능해져 효율성이 높아집니다.

### 5.3 데이터 재분배 (Rebalancing)
서비스 성장으로 인해 워커 노드를 추가한 경우, 기존 노드에 저장된 데이터를 새 노드로 옮겨 균형을 맞추는 과정이 필요합니다. Citus는 **Shard Rebalancer** 기능을 제공하여 서비스 중단 없이(Online) 데이터를 이동시킬 수 있습니다.
*   **동작 방식**: 백그라운드에서 샤드를 새 노드로 복제한 후, 메타데이터를 업데이트하고 이전 노드의 데이터를 삭제하는 방식으로 진행됩니다.

## 6. 고가용성(HA) 및 백업 전략
Citus는 분산 시스템이므로 단일 노드의 장애가 전체 서비스에 영향을 줄 수 있습니다. 이를 방지하기 위해 다음과 같은 전략을 사용합니다.

*   **고가용성(HA)**: PostgreSQL의 표준 **스트리밍 복제(Streaming Replication)**를 활용합니다. 각 워커 노드에 대해 하나 이상의 대기(Standby) 노드를 구성하여, 주 노드 장애 시 즉시 전환(Failover)함으로써 가용성을 확보합니다.
*   **백업 전략**:
    *   **pg_dump**: 메타데이터 및 소규모 데이터 백업에 적합하지만, 대규모 분산 데이터셋에는 시간이 너무 오래 걸립니다.
    *   **pg_basebackup**: 물리적 백업 방식으로, 각 워커 노드에서 개별적으로 수행하거나 스냅샷 기반의 백업 도구를 사용하여 전체 클러스터의 일관된 시점 복구를 구현합니다.

## 7. 장단점 및 제약 사항

### 7.1 분석 및 비교
Citus는 PostgreSQL의 생태계를 그대로 사용할 수 있다는 강력한 장점이 있지만, 분산 환경 특성상 일부 제약이 존재합니다.

*   **장점**:
    *   표준 SQL 및 PostgreSQL의 모든 기능(JSONB, PostGIS 등) 활용 가능.
    *   수평적 확장을 통한 무제한에 가까운 저장 용량 및 처리량 확보.
    *   멀티 테넌트 구조에서 극강의 성능 발휘.
*   **단점 및 제약**:
    *   **조인 제약**: 샤드 키가 다른 분산 테이블 간의 조인은 네트워크 비용이 많이 발생하며, 일부 복잡한 조인은 제한될 수 있습니다.
    *   **외래 키 제약**: 분산 테이블 간의 외래 키 설정은 샤드 키를 포함해야 하는 등 제약 사항이 있습니다.
    *   **분산 트랜잭션 오버헤드**: Citus는 분산 트랜잭션을 지원하지만, **2단계 커밋(2PC, Two-Phase Commit)** 방식을 사용합니다. 이로 인해 단일 노드 트랜잭션보다 성능 저하가 심하며, 특히 여러 샤드에 걸친 업데이트가 빈번할 경우 락(Lock) 경합이 발생하여 처리량이 급감할 수 있습니다.

### 7.2 데이터베이스 비교 표

| 비교 항목 | 일반 PostgreSQL | Citus (Distributed PG) | NoSQL (예: MongoDB) |
| :--- | :--- | :--- | :--- |
| **확장 방식** | 수직적 확장 (Scale-up) | 수평적 확장 (Scale-out) | 수평적 확장 (Scale-out) |
| **데이터 모델** | 관계형 (Strict Schema) | 관계형 (Strict Schema) | 문서형/키-값 (Flexible) |
| **트랜잭션** | 강력한 ACID 보장 | 분산 트랜잭션 지원 (오버헤드 존재) | 기본적으로 최종 일관성 (Eventual) |
| **조인 성능** | 매우 높음 (단일 노드) | 높음 (로컬 조인 시) / 낮음 (분산 조인 시) | 낮음 (애플리케이션 단 처리 필요) |
| **적합한 사례** | 중소규모 데이터, 복잡한 쿼리 | 대규모 데이터, 멀티 테넌트, 분석 | 비정형 데이터, 초고속 쓰기 |

## 8. 버전별 주요 변경 사항
Citus는 지속적인 업데이트를 통해 기능을 확장하고 있습니다.

*   **Citus 10.x**: 분산 테이블에 대한 인덱스 관리 최적화 및 쿼리 최적화 도구 강화.
*   **Citus 11.x**: 더 정교한 데이터 재분배(Rebalancing) 알고리즘 도입 및 PostgreSQL 최신 버전 호환성 확대.
*   **Citus 12.x**: 분산 쿼리 실행 계획의 가시성 개선 및 특정 윈도우 함수(Window Functions)의 분산 처리 지원 확대. 특히, 코디네이터의 병목 현상을 줄이기 위해 **"Coordinator-less"** 아키텍처(워커 노드가 직접 쿼리를 처리하는 방향)로의 지향점을 제시하며, 이전 버전에서 제한되었던 복잡한 SQL 연산자 및 함수들의 분산 실행 지원 범위를 대폭 넓혔습니다.