복사 0바이트로 운영 DB를 갈라 쓴다: db-branch(db-branch/db-branch) v0.2.7 심층 해부 — ZFS 클론 브랜치·정상 종료 스냅숏·Raft+ProxySQL 라우팅·AI 에이전트용 MCP, root RCE 수정과 박스 실측까지

한 줄 요약: db-branch/db-branch는 MySQL과 PostgreSQL 데이터베이스를 ZFS 클론으로 수 초 만에 “브랜치”하는 셀프호스트 도구입니다. 테라바이트급 DB라도 만드는 순간에는 한 바이트도 복사하지 않습니다(copy-on-write). PR마다 DB 한 벌, AI 에이전트용 일회용 샌드박스, 메이저 버전 업그레이드 리허설이 대표 용도입니다. 이 글은 2026-11-18 기준 최신 릴리스 v0.2.7(커밋 d662dbd)를 놓고 설계 문서와 소스를 함께 읽습니다. 정상 종료 스냅숏, Raft 클러스터, ProxySQL 라우팅, 크래시에도 끝까지 가는 체크포인트 복원, 그리고 같은 날 나온 root 권한 RCE 수정까지 다룹니다. 박스에서 직접 빌드하고 테스트를 돌린 결과도 함께 정리했습니다.

테크부터 경제, 생활까지. 복잡한 소식을 쉽게 풀어봅니다.

db-branch 한눈에 보기: 정상 종료한 베이스 스냅숏을 ZFS로 클론해 브랜치마다 전용 DB 프로세스를 띄우는 구조와 reset·checkpoint·upgrade·ttl. 하단은 v0.2.7 정보와 박스 실측 요약 (PIL로 직접 그린 일러스트)
db-branch 한눈에 보기: 정상 종료한 베이스 스냅숏을 ZFS로 클론해 브랜치마다 전용 DB 프로세스를 띄우는 구조와 reset·checkpoint·upgrade·ttl. 하단은 v0.2.7 정보와 박스 실측 요약 (PIL로 직접 그린 일러스트)

왜 지금 이 저장소인가

last30days 랭킹(쿼리 “AI agent repo”)에서 10위에 오른 항목은(두 쿼리를 합친 순위에서 이미 다룬 저장소와 30일 넘게 멈춘 저장소를 빼면 가장 높은 실제 GitHub 저장소) 2026-11-15 22:50(KST)에 올라온 Hacker News 글 “Show HN: db-branch – database branches in seconds for AI agents and CI, via ZFS”였습니다. 이 글을 쓰는 시점에 45점, 댓글 17개입니다. 저장소는 2026-11-12 18:58(KST)에 첫 공개 커밋이 올라왔습니다. 공개된 지 일주일이 안 됐고, 그 사이 릴리스 태그를 8개(v0.2.0~v0.2.7) 찍었습니다. 스타는 67개로 아직 작은 프로젝트입니다. 그런데도 다룰 가치가 있는 이유는 두 가지입니다.

  • 에이전트 시대의 실제 병목을 겨냥합니다. 코딩 에이전트에게 코드는 브랜치와 워크트리로 쉽게 격리해 줄 수 있지만, 데이터베이스는 여전히 공용 개발 DB 하나를 같이 쓰는 경우가 많습니다. db-branch는 MCP 서버를 내장해서 에이전트가 브랜치를 직접 만들고, 거기서 위험한 쿼리나 마이그레이션을 돌리고, 지우게 합니다.
  • 설계 문서가 이례적으로 촘촘합니다. docs/에 일본어 설계 문서가 15편 있습니다. ARC 메모리 예산, 크래시 의미론, uid 정렬, 혼합 OS 클러스터 같은 운영상의 함정을 근거와 함께 적어 두었습니다. 개발 규칙(CLAUDE.md)은 t-wada식 TDD와 “패키지 커버리지 95% 미만이면 실패”입니다.

HN 댓글에서 나온 쟁점도 평가에 바로 쓸 수 있습니다. “PostgreSQL은 크래시 일관성이 있으니 정상 종료 없이 스냅숏을 떠도 되지 않느냐”, “Postgres 18의 file_copy_method = clone으로 충분하지 않느냐”, “Database Lab(postgres.ai)과 뭐가 다르냐”, “브랜치를 원본에 머지할 수 있느냐” 같은 질문입니다. 작성자는 머지는 지원하지 않으며 충돌 해결이 가장 큰 과제라고 답했습니다. Database Lab과의 차이로는 “대부분의 DB 브랜칭 도구가 Postgres 중심이라 MySQL도 되는 걸 만들고 싶었다”를 들었습니다. 이 쟁점들은 아래 비교표와 주의점에서 다시 다룹니다.

항목 값 (2026-11-18 17시 무렵 KST 확인) 출처
최신 릴리스 v0.2.7, 2026-11-18 12:45 KST 게시. 태그 커밋 d662dbd(12:35 KST) GitHub Releases, git
상태 Beta. 1.0 전까지 API와 CLI 세부가 바뀔 수 있음 README, CHANGELOG
첫 공개 커밋 f021c4a “Initial public release”, 2026-11-12 18:58 KST git log
커밋 수 130개. 작성자 표기는 모두 Keisuke(Masuda) 한 명 git shortlog
스타 / 포크 / 열린 이슈 67 / 1 / 2 GitHub API
라이선스 코어 Apache-2.0 (Copyright 2026 Keisuke Masuda). 선택 패키지 db-branch-proxysql은 ProxySQL(GPL-3.0)을 동봉 LICENSE, NOTICE
언어 / 규모 Go 1.27.3 단일 바이너리. Go 약 6.6만 줄(이 중 테스트 약 3.4만 줄). 콘솔은 React + Vite(web/src 파일 119개) go.mod, wc 집계
지원 OS Ubuntu 24.04 / 26.04 LTS, amd64·arm64. Debian 12 이상은 MySQL만 지원 README, design.md §10

릴리스 흐름: 일주일, 태그 8개

버전 게시 시각 (KST) 핵심 변화
v0.2.0 11/13 20:11 첫 GitHub 릴리스 (Beta)
v0.2.1 11/13 20:51 40분 뒤 후속 릴리스
v0.2.2 · v0.2.3 태그만 있음 0.2.3: 콘솔 검색·필터, 베이스·브랜치 상세 페이지, 마이그레이션 검증용 MySQL 5.7/5.6 런타임(amd64 전용)
v0.2.4 11/15 12:55 init --evaluation, 콘솔 SQL 섹션, 브랜치 Pause/Resume(클러스터 프로토콜 18), Storage 트리 페이지
v0.2.5 11/15 14:53 arm64에서 MySQL 런타임 설치 실패 수정. 디버그 바이너리를 지워 8.4.13 기준 1.5GB → 1.1GB
v0.2.6 패키지 없음 보안 수정 태그였지만 커버리지 검사에서 릴리스가 멈춤. 태그를 옮길 수 없어 번호를 건너뜀
v0.2.7 11/18 12:45 보안: 콘솔·API 포트에 닿기만 하면 노드에서 root로 명령을 실행할 수 있던 문제 수정(아래 별도 절)

릴리스 속도만 보면 AI 에이전트 생태계의 다른 저장소와 비슷합니다. 차이는 CHANGELOG의 문체입니다. 각 항목이 “무엇이 바뀌었고, 사용자에게 무엇이 달라지는가”를 문장으로 설명합니다. 0.2.6을 건너뛴 이유까지 적어 둔 점은 운영 도구로서 신뢰를 주는 부분입니다.

핵심 개념: 베이스, 브랜치, 리셋 포인트

용어 실체 설계상 의미
런타임 mysql@8.4.13, postgres@18.6 같은 엔진 바이너리 묶음. 위치는 /var/lib/db-branch/runtimes/<engine>/<version>/ OS 패키지에 의존하지 않습니다. 버전 여러 개를 한 노드에 함께 둘 수 있습니다
베이스 덤프를 한 번 적재한 ZFS 데이터셋 + 런타임 1개 보통 마스킹한 운영 데이터를 넣습니다. 클러스터 전체에 전파됩니다
베이스 스냅숏 bases/prod@<세대> DB를 정상 종료한 뒤에만 뜹니다. 클론을 띄울 때 크래시 복구가 돌지 않게 하려는 것입니다
브랜치 베이스 스냅숏의 ZFS 클론 + 이를 datadir로 쓰는 전용 mysqld/postgres 프로세스 브랜치마다 포트 1개(기본 40000-40999), ProxySQL hostgroup 1개
리셋 포인트 branches/x@reset. init SQL을 적용하고 정상 종료한 뒤 뜬 스냅숏 그 노드에만 있습니다. 노드를 잃으면 브랜치는 lost가 되고 recreate로 다시 만듭니다
리더 / 베이스 오리진 Raft로 뽑힌 쓰기 담당 노드 / 베이스를 갱신해 내보내는 노드 두 역할은 분리돼 있습니다. 리더가 없어도 이미 있는 브랜치에는 계속 접속됩니다

아키텍처: 상태는 Raft, 데이터는 ZFS, 접속은 ProxySQL

3노드 클러스터 구조: 노드마다 ProxySQL → db-branch agent(Raft 내장) → 브랜치별 mysqld/postgres → ZFS 풀, 베이스는 zfs send/recv로 전파. 라우팅 우선순위와 클러스터 규칙은 docs/design.md 기준 (PIL 다이어그램)
3노드 클러스터 구조: 노드마다 ProxySQL → db-branch agent(Raft 내장) → 브랜치별 mysqld/postgres → ZFS 풀, 베이스는 zfs send/recv로 전파. 라우팅 우선순위와 클러스터 규칙은 docs/design.md 기준 (PIL 다이어그램)

db-branch는 Go 단일 바이너리입니다. 서브커맨드로 역할이 바뀝니다. 상주 데몬 db-branch agent는 systemd가 띄웁니다. 그 안에 Raft 스토어, ZFS 드라이버, 런타임 매니저, 엔진 러너, ProxySQL 리콘사일러, REST API, 콘솔, 확장 포인트가 모두 들어 있습니다. 나머지 서브커맨드는 에이전트의 Unix 소켓(/run/db-branch/agent.sock)이나 HTTPS로 말하는 CLI 클라이언트입니다. 외부 etcd는 쓰지 않습니다. hashicorp/raft를 바이너리에 내장했고, 노드 간 통신은 cluster init 때 만든 CA로 mTLS를 겁니다.

코드 구조는 클린 아키텍처를 따릅니다. 의존성은 바깥에서 안쪽으로만 향합니다. ZFS, 프로세스 기동, 네트워크 같은 부수효과는 infrastructure에 가둬 두고, usecase는 포트(인터페이스)로만 접근합니다. 이 원칙 덕분에 아래 박스 실측에서 ZFS 없이도 대부분의 비즈니스 로직 테스트가 돌아갑니다.

경로 역할 눈여겨볼 파일
internal/domain 엔티티, 값 객체, 포트. 외부 의존성 0개 branch.go, checkpoint.go, placement.go, anonymous.go
internal/usecase 브랜치, 런타임, 라우팅, 토큰, 라이선스, 업데이트 같은 유스케이스 16개 패키지 dbbranch/upgrade.go, dbbranch/follow.go
internal/interface CLI(cobra), HTTP API, 노드 간 API httpapi/mcp.go(MCP 도구 등록)
internal/infrastructure zfs, mysql, postgres, proxysql, raftstore, clusterpki 등 어댑터 31개 zfs/checkpoint.go, raftstore/fsm.go(Protocol = 18)
internal/app 컴포지션 루트. 배선만 하고 로직은 두지 않음. 커버리지 게이트 대상에서 빠지고 실기 통합 테스트로 확인 agent.go, cluster_loops.go
pkg/ext 유료·외부 모듈용 공개 확장 포인트. hashicorp/go-plugin 기반 별도 프로세스 plugin/host.go, license/license.go
web/ React + Vite 콘솔. 빌드 결과를 바이너리에 임베드. 브라우저 안에서만 도는 데모용 가짜 에이전트(demo-worker)도 있음 embed.go
api/openapi.yaml REST API 정의. 경로 70개(이 중 /v1 67개) CLI, 콘솔, MCP가 모두 이 API 하나를 씀

왜 “정상 종료 스냅숏”인가: 속도는 복사가 아니라 복구에서 갈린다

브랜치 생성 6단계와 체크포인트 복원 7단계(의도 기록 → 클론 → 정지 → rename → 교체 → promote → 기동). 크래시 일관성과 정상 종료 일관성의 차이 (design.md §5·checkpoints.md §4 기준 PIL 다이어그램)
브랜치 생성 6단계와 체크포인트 복원 7단계(의도 기록 → 클론 → 정지 → rename → 교체 → promote → 기동). 크래시 일관성과 정상 종료 일관성의 차이 (design.md §5·checkpoints.md §4 기준 PIL 다이어그램)

ZFS 클론 자체는 원래 즉시 만들어집니다. 진짜 시간을 잡아먹는 건 클론 위에서 DB가 뜰 때 도는 크래시 복구입니다. 실행 중인 InnoDB를 스냅숏하면 “전원이 막 나간 직후” 상태가 됩니다. 그 클론으로 만든 브랜치는 뜰 때마다 redo를 적용하고 undo를 되감아야 하고, 미반영 변경이 많을수록 느려집니다. 그래서 db-branch는 베이스 스냅숏과 리셋 포인트를 반드시 정상 종료 뒤에 뜹니다. MySQL은 SET GLOBAL innodb_fast_shutdown = 0으로 purge와 change buffer 병합까지 끝낸 다음 SHUTDOWN합니다. PostgreSQL은 CHECKPOINT 뒤 pg_ctl stop -m fast입니다. 정상 종료가 확인되지 않으면(MySQL은 에러 로그의 Shutdown complete, PG는 pg_controldata의 shut down) 스냅숏을 아예 뜨지 않고 실패시킵니다. 브랜치가 뜰 때 크래시 복구가 돌았다면 경고도 남깁니다.

HN에서 “Postgres는 크래시 일관성이 있으니 굳이 그럴 필요 없다”는 지적이 나왔습니다. 정합성만 보면 맞는 말입니다. db-branch가 노리는 건 정합성이 아니라 브랜치 기동 시간의 예측 가능성입니다. 대신 운영 DB를 직접 멈추는 게 아니라 읽기 복제본을 멈추거나 정기 백업에서 복원한 인스턴스로 베이스를 만드는 운영이 전제가 됩니다. 작성자도 HN 첫 댓글에서 “운영 DB를 멈추라는 뜻이 아니라 읽기 복제본이나 백업 복원 인스턴스를 쓰라는 것”이라고 설명했습니다.

공개 문서가 밝힌 자체 3노드 테스트 클러스터 수치는 PostgreSQL 브랜치 약 0.5초, MySQL 브랜치 약 3초이고, 생성 시 복사량은 0바이트입니다. 작성자 환경의 수치이므로 자기 데이터로 재야 합니다.

ZFS와 DB 설정: 브랜치 용도에 맞춘 기본값

대상 설정 이유 (design.md §7)
전체 데이터셋 compression=lz4, atime=off, xattr=sa 용량을 줄이고 불필요한 쓰기를 막음
MySQL·PG 데이터 recordsize=16K InnoDB 페이지 크기에 맞춤. PG도 8K면 압축 효율이 떨어져 16K
데이터셋 분할 브랜치 1개 = 데이터셋 1개 (redo/WAL을 분리하지 않음) 스냅숏과 클론을 여러 데이터셋에 걸쳐 맞추는 문제를 피함
DB 쓰기 최적화 MySQL innodb_doublewrite=OFF, innodb_flush_neighbors=0 / PG full_page_writes=off ZFS는 CoW라 페이지가 찢어지지 않음
ARC 상한 init 때 zfs_arc_max = 물리 메모리의 25%(기본) ARC가 InnoDB 버퍼 풀, shared_buffers와 메모리를 다투다 브랜치가 OOM으로 죽는 것을 막음
캐시 전략 primarycache=all 유지, 브랜치 DB 캐시는 128MB로 작게 브랜치들이 베이스 블록을 공유하므로 ARC가 공유 캐시 역할. 흔한 “DB 데이터셋은 metadata만 캐시” 설정은 여기서는 역효과
내구성 sync=standard, DB 쪽 내구성 설정은 그대로 개발·검증 용도지만 기본값은 보수적으로. 필요하면 브랜치 단위로 완화

실무에서 가장 쓸모 있는 통찰은 ARC 항목입니다. 브랜치 N개는 베이스 블록 대부분을 공유하지만 DB 버퍼 풀은 각자 따로 잡습니다. 그래서 공유분은 ARC(한 번만 캐시)에 맡기고 프로세스별 캐시는 줄이는 편이 노드당 브랜치 밀도에 유리합니다. 배치 스케줄러도 이 예산 모델을 씁니다. “물리 메모리 − ARC 상한”과 “물리 메모리의 75%” 중 작은 값을 넘기는 배치는 하지 않습니다.

체크포인트: 리셋을 깨뜨리지 않는 “줄 바꿔 끼우기”

리셋은 단순합니다. 서버를 멈추고 zfs rollback @reset 한 뒤 다시 띄웁니다. 어차피 버릴 상태라 즉시 종료해도 됩니다. 체크포인트가 들어오면 이야기가 달라집니다. zfs rollback은 그 뒤에 뜬 스냅숏을 지워 버리기 때문입니다. 그래서 복원은 7단계 교체로 구현합니다. 체크포인트를 history/x/new로 클론하고, 라이브 데이터셋을 history/x/<n>으로 이름을 바꾸고, 새 클론을 branches/x로 올린 다음 zfs promote를 반복합니다. 이렇게 하면 기존 체크포인트가 모두 살아남고, 어느 시점으로든 다시 복원할 수 있습니다. 두 가지 안전장치가 눈에 띕니다. 첫째, 베이스 스냅숏에서 이어진 클론 관계는 절대 promote하지 않습니다(그러면 베이스가 브랜치의 클론이 돼 버립니다). 둘째, 브랜치를 지울 때 zfs destroy -R을 쓰지 않고, 클론 쪽부터 하나씩 지웁니다.

크래시 내성은 “의도(intent)”를 ZFS 사용자 속성에 먼저 기록하는 방식으로 얻습니다. 에이전트가 어느 단계에서 죽든, 재시작한 Recover가 디스크 상태를 보고 남은 단계를 앞으로만 진행합니다. 문서에 따르면 결과는 “원래 상태” 아니면 “복원 완료” 둘 중 하나입니다. 테스트는 복원의 모든 부수효과 직전에 에이전트를 죽이고(이중 크래시 포함) 재시작 후 상태를 확인합니다.

공식 저장소 이미지(docs/assets/branch-graph.png): 웹 콘솔의 체크포인트 그래프. 복원할 때마다 새 '선(line)'이 생기고 이전 체크포인트는 그대로 남는 모습. 하단 트랜잭션 목록과 'Restore to #2'는 유료 history 모듈 기능. 출처: db-branch/db-branch, Apache-2.0
공식 저장소 이미지(docs/assets/branch-graph.png): 웹 콘솔의 체크포인트 그래프. 복원할 때마다 새 ‘선(line)’이 생기고 이전 체크포인트는 그대로 남는 모습. 하단 트랜잭션 목록과 ‘Restore to #2’는 유료 history 모듈 기능. 출처: db-branch/db-branch, Apache-2.0

라우팅: 접속 문자열 하나로 브랜치 고르기

항목 MySQL PostgreSQL
클라이언트 포트(ProxySQL) 6033 6133
관리 인터페이스 127.0.0.1:6032 127.0.0.1:6132
설정 테이블 mysql_servers / mysql_users / mysql_query_rules pgsql_servers / pgsql_users / pgsql_query_rules
브랜치 지정 방법(우선순위 순) 1) sqlcommenter 호환 쿼리 주석 /*db_branch='feature-x'*/ → 2) 접속 사용자명 = 브랜치명 → 3) 사용자의 기본 브랜치
정합성 규칙 transaction_persistent=1: 트랜잭션 도중에는 브랜치를 바꾸지 않음. 주석이 없는 쿼리는 정규식 1회만 평가하도록 규칙을 2단으로 구성
수렴 방식 Raft 상태를 유일한 정본으로 삼고, 각 노드가 자기 ProxySQL을 변경 즉시 재설정 + 5초 주기 재점검. ProxySQL Cluster 동기화는 쓰지 않음

쿼리 주석 방식은 강력하지만 문서 스스로 경고하는 함정이 있습니다. 주석 지정은 모든 브랜치에 공통인 사용자로 접속한다는 전제라서, 그 사용자는 아무 브랜치에나 들어갈 수 있습니다. 그래서 사용자 단위로 끌 수 있게 설계했습니다. 또 mysql CLI는 기본값으로 주석을 지우므로 -c 옵션이 필요합니다. 앱 미들웨어에서 X-DB-Branch 같은 HTTP 헤더를 읽어 주석을 붙이면 요청 단위로 브랜치를 바꿀 수 있다는 점은 프리뷰 환경 구성에 유용합니다.

AI 에이전트 연결: MCP 서버

MCP 서버는 각 노드 콘솔과 같은 HTTPS 포트에서 뜹니다(https://<node>:7080/v1/mcp, Streamable HTTP, 무상태). 인증은 Authorization: Bearer dbb_... 토큰입니다. 비밀값은 발급할 때 한 번만 보여 주고, Raft에는 해시만 저장합니다. 도구 호출은 REST API와 같은 인가 경로를 지나고, 감사 로그의 행위자는 token:<id>로 남습니다.

도구 동작 제약·주의
list_bases / list_branches / get_branch 베이스·스냅숏 목록, 브랜치 목록, 접속 정보(dsn) dsn에 비밀번호가 들어 있음
create_branch 베이스에서 브랜치를 만들고(완료까지 대기) dsn 반환. ttl, init_sql, runtime 지정 가능 0.2.7부터 init SQL은 브랜치 로그인 권한으로 실행
query 브랜치에서 SQL 1문 실행 최대 1000행, 30초
create_checkpoint / list_checkpoints / restore_checkpoint 저장, 목록, 복원 복원은 현재 상태를 자동 저장하지 않음. 위험한 작업 전에 먼저 저장해야 함
check_upgrade / upgrade_branch 업그레이드 사전 점검(error/warning/info), 브랜치 하나만 업그레이드 업그레이드 전 자동 체크포인트를 뜨고, 실패하면 자동 롤백
reset_branch / extend_branch / delete_branch 생성 직후로 리셋, 만료 연장, 삭제 리셋해도 체크포인트는 남음
토큰 스코프 branches(기본): 브랜치 생성·사용·삭제와 읽기만 / full: admin과 동일 에이전트에는 branches + --ttl을 권장. branches 토큰은 설정·토큰·루트 사용자 정보를 읽을 수 없음

Claude Code 연결은 문서상 세 줄입니다. 노드의 자기서명 인증서를 NODE_EXTRA_CA_CERTS로 지정하고 claude mcp add --transport http db-branch https://<node>:7080/v1/mcp --header "Authorization: Bearer <token>"을 실행합니다. 저장소에 남은 검증 기록(2026-11-10)은 이렇습니다. 노드 1에서 발급한 토큰으로 노드 3의 MCP를 호출해 브랜치를 노드 2에 만들고, 마스킹된 행을 조회하고, 2행을 지운 뒤 리셋해 복구했습니다. branches 토큰으로 베이스를 지우려 하면 403, 토큰 없이 호출하면 401이 나왔습니다.

v0.2.7 보안 수정: 공개 스냅숏 + init SQL = root 명령 실행

오늘 릴리스는 기능 추가가 아니라 심각한 취약점 수정입니다. 로그인 없이도 공개 스냅숏에서 브랜치를 만들 수 있는데, 이때 받은 init_sql이 에이전트(root) 권한의 psql/mysql 클라이언트로 실행됐습니다. 그래서 \!(psql)나 system(mysql) 같은 클라이언트 명령이 노드에서 그대로 돌았습니다. PostgreSQL에서는 브랜치 로그인이 슈퍼유저였기 때문에 COPY ... TO PROGRAM도 통했습니다.

지점 0.2.5 이하 0.2.7
init SQL 실행 주체 에이전트(root)가 클라이언트로 실행 브랜치 로그인. PG는 psql 없이 서버가 직접 읽음(평문 SQL과 \connect만 허용), MySQL은 --binary-mode
익명 호출 + init_sql 허용 403
PG 브랜치 로그인 슈퍼유저 db_branch_owner 역할의 멤버. 객체 생성·변경·삭제는 가능
MySQL 브랜치 로그인 위 권한 제한 없음 FILE, SUPER, SHUTDOWN, RELOAD, PROCESS, CREATE USER, 복제, GRANT OPTION 없음. secure_file_priv=NULL, local_infile=OFF
소켓·설정 파일 그룹 db-branch(DB 서버와 같은 그룹) 새 그룹 db-branch-admin. DB 서버 유닛에서는 /run/db-branch, /etc/db-branch가 보이지 않음
기존 브랜치 — 에이전트 시작 시와 브랜치 서버 기동 시(리셋·복원·재개 포함) 자동 교정

호환성 영향도 있습니다. init SQL에서 CREATE USER, GRANT, COPY ... PROGRAM, 신뢰되지 않은 확장의 CREATE EXTENSION, \connect 외의 psql 명령을 더 이상 쓸 수 없습니다. 이런 작업은 스냅숏을 뜨기 전에 베이스에서 admin으로 해 둬야 합니다. 0.2.5 이하에서 익명 생성(공개 스냅숏)을 열어 두었다면 바로 올리는 것이 맞습니다. 익명 생성에는 별도 상한도 있습니다. 전체 상한, 베이스별 상한, 접속 주소별 시간당 횟수(branch.anonymous_rate, 기본 5)입니다. 주소별 횟수는 노드 메모리에서만 세고, IPv6는 /64 단위로 묶으며, X-Forwarded-For는 읽지 않습니다.

설치와 평가: 3단계

README가 제시하는 평가 경로는 세 가지입니다. ① 브라우저 데모(demo.db-branch.com, 실제로 만들어지는 것은 없음). ② Mac/Windows에서는 Multipass로 Ubuntu 24.04 VM을 띄워 파일 기반 ZFS 풀과 MySQL 8.4 샘플 베이스 shop을 약 2분 만에 준비합니다. ③ 자기 Ubuntu 서버에는 APT 저장소로 설치합니다.

# ② 평가 VM (README 그대로)
multipass launch 24.04 --name db-branch-eval --memory 4G --disk 30G --timeout 900 \
  --cloud-init https://raw.githubusercontent.com/db-branch/db-branch/main/scripts/eval-cloud-init.yaml
multipass exec db-branch-eval -- cloud-init status --wait
multipass shell db-branch-eval   # sudo db-branch branch create try --base shop --ttl 1h --record

# ③ 서버 설치 (서명 키 지문 3F404C4E5D49FA653F8385692C6E89E341D4D7A5)
curl -fsSL https://apt.db-branch.com/db-branch.gpg | sudo tee /usr/share/keyrings/db-branch.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/db-branch.gpg] https://apt.db-branch.com stable main" | sudo tee /etc/apt/sources.list.d/db-branch.list
sudo apt update && sudo apt install db-branch
sudo db-branch init --pool <zpool>

# 첫 브랜치
db-branch runtime install postgres@18.6
db-branch base create prod --runtime postgres@18.6 --dump prod.sql.gz
db-branch branch create feature-x --base prod --ttl 72h
db-branch branch checkpoint feature-x --name before-migration
db-branch branch restore feature-x before-migration
db-branch branch upgrade feature-x --runtime mysql@8.4.13 --check-only   # MySQL 브랜치의 경우

평가 VM에서는 유료 모듈이 키 없이 30일 동안 동작합니다(--record는 history 모듈 기능). 파일 기반 풀이라 느리므로 실제 데이터용이 아닙니다. arm64(Apple Silicon)에서는 Oracle이 minimal 빌드를 내지 않아 MySQL 다운로드가 약 800MB입니다(Intel은 약 80MB). 패키지는 설치할 때 디스크나 네트워크를 건드리지 않습니다. ZFS 풀 설정은 init을 명시적으로 실행할 때만 일어납니다.

박스 실측: ZFS 없는 환경에서 어디까지 확인되나

박스 실측 대시보드: 소스 빌드 15.5초, 26.2MB 바이너리, 28개 패키지 테스트 통과, 익명 init_sql 403 회귀 테스트 PASS, ZFS·데몬이 없어 CLI는 agent.sock 연결 단계에서 멈춤
박스 실측 대시보드: 소스 빌드 15.5초, 26.2MB 바이너리, 28개 패키지 테스트 통과, 익명 init_sql 403 회귀 테스트 PASS, ZFS·데몬이 없어 CLI는 agent.sock 연결 단계에서 멈춤

이 박스는 Debian 13 x64이고 일반 사용자(uid 1000)로 돌아갑니다. ZFS, Docker, MySQL은 없습니다. 그래서 실제 브랜치 생성은 할 수 없습니다. 대신 v0.2.7 태그 커밋 d662dbd를 클론해 빌드와 단위 테스트, CLI 동작을 확인했습니다.

확인 항목 명령 실제 결과
빌드 CGO_ENABLED=0 go build -trimpath -ldflags "-s -w -X main.version=0.2.7" ./cmd/db-branch 성공. real 15.5초(의존성 다운로드 포함), 바이너리 26,198,176바이트. web/dist를 빌드하지 않아 콘솔 자산은 빠진 상태
버전 db-branch version db-branch 0.2.7
CLI 표면 db-branch --help, branch --help 최상위 명령 help 포함 15개(admin, agent, backup, base, branch, cluster, init, module, route, runtime, settings, token, update 등). branch 하위 명령 14개(checkpoint, pause/resume, recreate, upgrade 포함)
데몬 없이 CLI 실행 db-branch branch list cannot reach the db-branch agent (is it running? try: sudo systemctl status db-branch): ... dial unix /run/db-branch/agent.sock: connect: no such file or directory. 원인과 다음 조치를 함께 보여 줌
단위 테스트 go test -cover (domain, usecase 16개, zfs, proxysql, interface 3개, pkg 3개 + mysql, postgres, raftstore) 28개 패키지 모두 ok. 커버리지 예: domain 97.3%, usecase/dbbranch 95.2%, infrastructure/zfs 97.6%, proxysql 98.1%, httpapi 96.1%
보안 회귀 테스트 go test -run 'TestAnonymous_ログインなしはinit_sqlを渡せない' ./internal/interface/httpapi/ PASS. 익명 요청의 "COPY (SELECT 1) TO PROGRAM 'id'"는 403이고 브랜치가 만들어지지 않음. 공백뿐인 init_sql은 202, 로그인 사용자는 202
테스트 규모 func Test 집계 1,369개. 테스트 이름이 일본어 문장(“ログインなしはinit_sqlを渡せない”)이라 사양서처럼 읽힘

ZFS 드라이버 테스트(97.6%)가 실기 없이 통과하는 이유는 zfs 호출을 실행기 인터페이스 뒤로 숨겼기 때문입니다. 실제 zfs, systemd, mysqld를 건드리는 검증은 make integration(root 권한과 실제 풀 tank 필요)으로 분리돼 있습니다. 바꿔 말하면 이 박스 실측은 로직과 보안 규칙의 정합성만 보여 줄 뿐, 생성 속도나 크래시 복원은 검증하지 못했습니다. 그 부분은 평가 VM이나 ZFS가 있는 테스트 서버에서 직접 재야 합니다.

대안 비교

도구 엔진 복제 메커니즘 배포 형태 라이선스 머지 이럴 때
db-branch MySQL(5.6~9.x 런타임) + PostgreSQL ZFS 클론, 브랜치마다 DB 프로세스 셀프호스트 전용(호스팅 버전 없음), Raft 클러스터 코어 Apache-2.0 + 유료 모듈 없음(일회용 전제) MySQL 비중이 크고, 자기 서버에서 PR·에이전트용 DB를 찍어 내야 할 때
Database Lab Engine (postgres-ai/database-lab-engine) PostgreSQL 씬 클론(ZFS 기반, HN 댓글·작성자 언급) 셀프호스트 Apache-2.0 — Postgres 전용으로 성숙한 생태계를 원할 때
Neon (neondatabase/neon) PostgreSQL 스토리지·컴퓨트 분리 아키텍처의 브랜칭 관리형 서비스 + 오픈소스 코드 Apache-2.0 — 서버리스 Postgres와 scale-to-zero가 필요할 때
PostgreSQL 18 file_copy_method = clone PostgreSQL 18+ CREATE DATABASE ... STRATEGY=FILE_COPY 시 copy_file_range() 등으로 블록 공유 위임 DB 내장 기능 PostgreSQL License — 단일 인스턴스 안에서 가볍게 DB 복제본을 만들 때(파일시스템 지원 필요)
Dolt (dolthub/dolt) MySQL 호환 자체 엔진 엔진 내부 버전 관리 셀프호스트 등 Apache-2.0 있음(Git식) 데이터 자체를 Git처럼 diff·merge해야 할 때

요점은 이렇습니다. db-branch는 엔진 내부를 건드리지 않고 파일시스템 한 층 아래에서 브랜칭합니다. 그래서 MySQL과 PostgreSQL을, 그것도 여러 버전을 같은 방식으로 다룹니다. 업그레이드 리허설(branch upgrade --check-only, 5.6→5.7→8.0 순차 업그레이드)은 이 설계가 주는 고유한 장점입니다. 반대로 데이터 머지나 rebase는 구조적으로 어렵습니다. 작성자도 머지는 “언젠가 해 보고 싶지만 충돌 해결이 과제”라고 답했습니다.

에디션 구조와 라이선스

구분 포함 기능 배포
코어 (이 저장소) 브랜치, 베이스, 런타임, 클러스터, CLI, API, 웹 콘솔, MCP, 모니터링(Prometheus), 알림(Slack·웹훅), 상한이 있는 익명 브랜치, 베이스 정기 갱신, 클러스터 상태 백업 Apache-2.0
무료 모듈 proxysql(라우팅), greenmask, greenmask-mysql, anon(데이터 마스킹) 같은 APT 저장소. ProxySQL은 GPL-3.0
유료 모듈 auth/SSO, audit, history(트랜잭션 기록, 임의 시점 복원), diff, FSx 스토리지 클로즈드 소스, 셀프호스트, 월·연 라이선스 키(ed25519 서명, 오프라인 검증)

OSS 코어의 기본 인증은 admin 한 명의 비밀번호와 “인증되면 모두 허용”입니다. 여러 사용자, RBAC, SSO, 감사는 유료 모듈의 영역입니다. 다만 OSS 버전에서도 모든 API 호출은 Authorizer와 AuditSink 경로를 반드시 지납니다. 모듈만 추가하면 빠짐없이 기록되도록 하기 위해서입니다. 위 체크포인트 그래프의 트랜잭션 목록과 “Restore to #2” 같은 기능은 유료 history 모듈 기능이라는 점도 구분해서 봐야 합니다.

주의점과 한계

항목 내용 대응
성숙도 Beta. 공개 일주일, 메인테이너 1명, 스타 67개. 지원 약속 없음(SUPPORT.md) 버전 고정. CHANGELOG의 “What changes for you”를 읽고 업그레이드
보안 이력 0.2.5 이하에 root RCE 경로 존재(익명 생성 + init_sql) 0.2.7 이상 필수. 콘솔·API 포트(7080)를 신뢰 네트워크로 제한
플랫폼 종속 Linux + ZFS 필수. Ubuntu 24.04/26.04 기준, Debian은 MySQL만. Kubernetes Operator는 비목표 전용 VM이나 베어메탈에 별도 풀 구성
일관성 모델 체크포인트는 크래시 일관성만 보장(앱 수준 아님). 복원 중 접속 불가(MySQL 약 2초, PG 약 0.7초) 테스트 하네스가 재연결을 처리하게 구성
노드 장애 리셋 포인트·체크포인트는 노드 로컬. 노드를 잃으면 브랜치는 lost, recreate해도 체크포인트는 이어지지 않음 브랜치는 일회용으로 취급, 중요한 상태는 베이스로 승격
운영 DB 영향 베이스 스냅숏을 뜰 때 해당 DB 정상 종료 필요 읽기 복제본이나 백업 복원 인스턴스를 베이스 원천으로 사용
데이터 보호 운영 데이터를 그대로 브랜치하면 개인정보가 개발 환경과 에이전트에 노출됨 마스킹 모듈(greenmask/anon)로 마스킹한 베이스를 쓰고, 공개 스냅숏은 검증된 것만
혼합 OS 클러스터 PG 브랜치는 원 스냅숏과 같은 배포판 노드에만 배치(정렬 라이브러리 차이로 인한 인덱스 손상 방지). uid/gid는 클러스터 전체에서 통일 필요 노드 OS를 통일하거나 cluster align-ids 활용
문서 언어 설계 문서는 일본어. 영어 사용자 문서는 공식 사이트에 따로 있음 설계 판단을 확인하려면 docs/ 원문을 번역해 읽기

도입 체크리스트 (실무자용)

  1. 데모 → 평가 VM 순서로 확인하세요. 브라우저 데모로 UX를, Multipass VM으로 실제 생성·리셋·체크포인트 시간을 자기 노트북에서 재 봅니다.
  2. 베이스 원천을 정하세요. 운영 DB를 멈출 수는 없으니 복제본 정지 또는 백업 복원 파이프라인을 정하고, 마스킹을 베이스 단계에 넣습니다.
  3. 메모리 예산을 계산하세요. 물리 메모리 = OS 예비 + ARC 상한 + 브랜치당 DB 메모리 × N입니다. 동시 브랜치 수 목표에서 거꾸로 계산합니다.
  4. 에이전트에는 좁은 토큰을 주세요. branches 스코프 서비스 토큰에 --ttl을 걸고, 에이전트 지시문에 “위험 작업 전 create_checkpoint“를 넣습니다.
  5. CI에서 PR별 브랜치를 만드세요. branch create --ttl → 마이그레이션 → 테스트 → 삭제 순서이고, 실패해도 TTL이 청소합니다.
  6. 업그레이드 리허설에 쓰세요. branch upgrade --check-only로 MySQL 8.0→8.4 같은 메이저 업그레이드의 걸림돌을 미리 목록으로 받습니다.
  7. 0.2.7 이상으로 고정하고 포트를 닫으세요. 익명 생성은 정말 필요할 때만, 베이스별 상한과 함께 엽니다.

총평

db-branch의 아이디어 자체는 새롭지 않습니다. ZFS 스냅숏과 클론으로 DB 사본을 찍는 방법은 많은 팀이 셸 스크립트로 이미 써 왔고, HN 댓글에도 그런 경험담이 여럿 나옵니다. 이 저장소의 가치는 그 스크립트가 운영에서 부딪히는 문제를 하나씩 설계로 막아 둔 데 있습니다. 정상 종료 스냅숏, ARC 예산, 크래시에도 끝까지 가는 복원, 베이스를 promote하지 않는 규칙, uid 정렬, 혼합 OS 배치 제약이 그 예입니다. 거기에 MySQL 다중 버전, ProxySQL 라우팅, MCP를 얹어 “에이전트에게 진짜 같은 DB를 맡겼다가 버리는” 흐름을 완성했습니다. 반면 공개 일주일 만에 root RCE를 고친 Beta이고, 메인테이너가 한 명이라는 점은 무겁게 봐야 합니다. 지금 할 만한 일은 평가 VM에서 자기 덤프 하나로 생성·리셋·체크포인트 시간을 재 보고, 에이전트에 branches 토큰 하나를 쥐여 줘서 마이그레이션 리허설을 맡겨 보는 정도입니다. 그 결과가 좋으면 CI의 PR별 DB부터 붙여 보는 순서를 권합니다.

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다