GitDB: GitHub 저장소를 서버리스 RDB처럼 쓰는 TypeScript 라이브러리

2026년 6월 현재, 서버리스 앱의 데이터 저장 문제는 여전히 골치 아픈 영역입니다. 데이터는 필요한데 DB 서버는 돌리고 싶지 않은 상황이 너무 많죠. 크롬 익스텐션, 정적 앱, 데모, AI 에이전트, 작은 내부 툴 — 이런 경우에 매번 백엔드를 세우는 건 과한 일입니다. Show HN에 올라온 GitDB는 이 문제를 GitHub 저장소 하나로 풀어낸 흥미로운 TypeScript 라이브러리입니다. 서버리스 RDB인데 백엔드가 GitHub인 셈이죠.

GitDB가 뭔가

GitDB는 @3xhaust/gitdb라는 패키지로 배포되는 TypeScript 라이브러리입니다. 이름 그대로 GitHub 저장소를 데이터 저장소로 쓰는 RDB 같은 데이터베이스입니다. 데이터는 repo 안에 manifest, mutation log, snapshot 같은 파일로 커밋되고, Git history가 그대로 데이터 변경 이력이 됩니다. Postgres 같은 일반 DB를 대체하려는 게 아닙니다. 익스텐션, 정적 앱, 에이전트, 작은 툴에서 "DB 서버 없이 GitHub repo 하나를 데이터 저장소로 쓰는" 선택지를 만드는 게 목표입니다.

핵심 기능

GitDB의 현재 구현 표면적은 다음과 같습니다.

| 영역 | 지원 기능 |

|------|----------|

| 서버리스 export | @3xhaust/gitdb/browser (fetch 기반 + Web Crypto), @3xhaust/gitdb (Node + Octokit) |

| 테이블 API | insert, insertMany, upsert, upsertMany, select, first, deleteWhere |

| SQL 엔진 | CREATE TABLE, INSERT, DELETE, SELECT, joins, grouping, ordering, aggregates |

| GitHub 스토리지 | 평문/암호화 manifest·log 저장, non-force Git ref 업데이트 |

| 로컬 스토리지 | Node 개발·CLI용 평문/암호화 저장 |

| 내구성 | Manifest-gated mutation log replay |

| 동시성 | 데이터베이스당 단일 writer, branch conflict 시 재시도 |

| CLI | gitdb keygen, gitdb query, gitdb check |

어떤 경우에 쓰고, 어떤 경우에 피하나

GitDB README는 권장 사용처와 비권장 사용처를 명확히 구분합니다.

| 적합한 경우 | 부적합한 경우 |

|-------------|---------------|

| 프로젝트/앱당 GitHub repo 1개 (예: my-app-db) | 고 throughput OLTP |

| 익스텐션, 정적 앱, 데모, 에이전트, 툴용 백엔드 DB 불필요 | 저지연 multi-writer 워크로드 |

| 테이블·SQL·트랜잭션·인덱스를 갖춘 RDB-like API | 대규모 분석 |

| repo 파일을 직접 보고 검토할 수 있는 평문 모드 | 비밀값 관리 |

| manifest·log가 GitHub에서 불투명한 암호화 모드 | 클라이언트 토큰으로 노출되면 안 되는 데이터 |

| 내구성 있는 이력 = Git history 그 자체 | — |

즉 저빈도 앱 데이터, 데모, internal tool처럼 변경 이력과 배포 단순성이 더 중요한 경우를 위한 도구입니다. GitHub API latency와 rate limit이 있으므로 hot OLTP나 realtime multi-writer에는 맞지 않습니다.

브라우저에서 시작하기

@3xhaust/gitdb/browser는 fetch 기반 GitHub 스토어와 Web Crypto를 사용하므로 서버가 없는 앱에서도 그대로 동작합니다. 간단한 TODO 예제입니다.

import { defineTable, GitDb, GitHubFetchPlaintextStore } from "@3xhaust/gitdb/browser"
import { z } from "zod"

const TodoRow = z.object({
  id: z.string(),
  title: z.string(),
  done: z.boolean(),
})

const Todo = defineTable({
  columns: { done: "BOOLEAN", id: "STRING", title: "STRING" },
  indexes: [{ columns: ["done"], name: "todos_done_idx" }],
  name: "todos",
  primaryKey: "id",
  row: TodoRow,
})

const db = await GitDb.open({
  store: new GitHubFetchPlaintextStore({
    branch: "main",
    owner: "your-github-user",
    prefix: "gitdb/v1",
    repo: "my-extension-db",
    token: userProvidedGithubToken,
  }),
  syncSchema: true,
  tables: [Todo],
})

const todos = db.table(Todo)
await todos.upsert({ done: false, id: "t1", title: "Ship extension sync" })
const openTodos = await todos.select({ done: false })

익스텐션에 올릴 때는 GitHub API host permission을 manifest에 넣고, 광범위한 personal token을 하드코딩하지 말아야 합니다. user-scoped token이나 OAuth 흐름을 쓰는 게 안전합니다.

암호화 모드

민감도가 높은 데이터라면 AES-GCM 기반 암호화 모드를 쓸 수 있습니다. 32바이트 키를 base64url로 전달하기만 하면 manifest와 log가 GitHub에서 불투명하게 보입니다.

import {
  createWebAesGcmCipher, GitDb, GitHubFetchEncryptedStore,
} from "@3xhaust/gitdb/browser"

const cipher = await createWebAesGcmCipher(base64UrlEncoded32ByteKey)
const db = await GitDb.open({
  store: new GitHubFetchEncryptedStore({
    branch: "main",
    owner: "your-github-user",
    prefix: "gitdb/v1",
    repo: "my-private-db",
    token: userProvidedGithubToken,
  }, cipher),
})

Repository Layout

평문 모드에서는 repo에 사람이 읽을 수 있는 JSON이 그대로 커밋됩니다. gitdb/v1/manifest.json이 commit boundary 역할만 하고, manifest에 등록된 log segment만 replay되므로 orphan 파일이 DB 상태가 되는 일은 없습니다.

gitdb/v1/
  manifest.json
  log/
    00000000000000000001.json
    00000000000000000002.json
  snapshot.json
  todos/
    schema.json
    pages.json
    pages/000000.json
    indexes.json

암호화 모드에서는 같은 구조에서 확장자만 .enc로 바뀝니다.

Node / CLI

Node에서는 local store를 직접 쓸 수 있고, CLI 헬퍼도 제공됩니다.

import { defineTable, GitDb, LocalPlaintextStore } from "@3xhaust/gitdb"
const db = await GitDb.open({ store: new LocalPlaintextStore({ root: ".gitdb" }) })

gitdb keygen
GITDB_ENCRYPTION=off GITDB_ROOT=.gitdb gitdb check
GITDB_ENCRYPTION=off GITDB_ROOT=.gitdb \
  gitdb query "CREATE TABLE todos (id STRING, title STRING)"

GitHub-backed store는 같은 환경변수 셰이프(GITDB_GITHUB_OWNER, GITDB_GITHUB_REPO, GITDB_GITHUB_BRANCH, GITDB_GITHUB_PREFIX, GITDB_GITHUB_TOKEN)로 설정합니다.

벤치마크와 예제

examples/api-plaintext, examples/api-encrypted 두 예제가 repo에 들어 있고, corepack pnpm example으로 실제 GitHub repo를 만들고 데이터를 쓰고 다시 읽는 전체 플로우를 돌려볼 수 있습니다. GITDB_GITHUB_OWNER, GITDB_GITHUB_TOKEN, GITDB_KEY만 채우면 기본 repo 이름은 gitdb-example-db로 잡힙니다.

벤치마크는 corepack pnpm benchmark, benchmark:compare, benchmark:compare:github로 실행할 수 있고, GITDB_BENCH_ROWS=250처럼 row 수를 지정하면 insert·filtered select·join·filtered delete operation timing을 측정합니다. GitHub 프로파일은 실제 repo에 커밋하므로 API latency와 commit 시간이 그대로 포함됩니다.

커뮤니티 반응

긱뉴스에 달린 댓글 반응은 엇갈립니다. "몇 년 전에 rate limit 때문에 시도하다가 포기했던 내용인데, 잘 됐으면 좋겠다"는 응원이 있는가 하면, "Git이 불안정한데 정합성 중요한 걸 관리하기에 적합할까"라는 의구심, "아무 의미 없는 프로젝트... 파일 db네"라는 회의도 있습니다. 솔직히 일반 서비스 백엔드를 GitDB로 대체하자는 주장은 아니고, README도 명시적으로 hot OLTP·저지연 multi-writer는 부적합이라 못 박고 있어 도구의 용도를 자기 위치에 맞게 쓰면 되는 영역입니다.

핵심 요약

• 서버리스 RDB-like 데이터베이스, 백엔드는 GitHub repo
• 패키지: @3xhaust/gitdb (Node) / @3xhaust/gitdb/browser (서버리스)
• 테이블 API (insert/upsert/select/deleteWhere) + SQL 엔진 (SELECT/JOIN/GROUP BY/aggregate)
• 평문/암호화 모드, Manifest-gated mutation log replay로 내구성
• 추천 대상: 익스тен션, 정적 앱, 데모, AI 에이전트, 내부 툴
• 비추천: 고 throughput OLTP, 저지연 multi-writer, 대용량 분석, 비밀값 관리
• 라이선스: MIT
• GitHub: https://github.com/3x-haust/gitdb
• npm: https://www.npmjs.com/package/@3xhaust/gitdb