Ghost CMS는 12개의 테이블과 80개 이상의 컬럼을 가지고 있습니다. 각각 무엇을 의미할까요?

Ghost는 3만 개 이상의 GitHub 스타를 보유하며 수백만 개의 블로그를 구동하고 있는 가장 인기 있는 오픈 소스 블로깅 플랫폼 중 하나입니다.

Ghost의 데이터베이스는 10년에 걸쳐 진화해 왔습니다. 2015년의 posts와 users부터 2025년 v6.0의 대대적인 정리 작업에 이르기까지: 8번의 마이그레이션 (migrations), 12개의 테이블, 80개 이상의 컬럼, 그리고 Stripe 결제, 이메일 추적, 멤버십 시스템이 추가되었습니다.

SQL 마이그레이션 (migration) 파일들은 모두 migrations/ 디렉토리에 있습니다. 하지만 단 하나의 주석도 각 필드가 실제로 무엇을 의미하는지 설명해주지 않습니다.

이 질문들에 답할 수 있습니까?

Ghost 코드베이스의 마이그레이션 예시입니다:

  ALTER TABLE posts DROP COLUMN created_by;
  ALTER TABLE posts DROP COLUMN updated_by;
  ALTER TABLE users DROP COLUMN created_by;
...

안전한 정리일까요, 아니면 위험한 파괴일까요? 왜 created_by를 삭제할까요? 무엇이 그것을 대체했나요?

또는 posts 테이블을 보겠습니다:

  `type` VARCHAR(50) DEFAULT 'post'
  `status` VARCHAR(50) DEFAULT 'draft'
  `visibility` VARCHAR(50) DEFAULT 'public'
...

status의 유효한 값은 무엇인가요? draft/published인가요, 아니면 active/inactive인가요? visibility에 paid 등급이 추가된 것은 언제인가요? 왜 locale은 6자리에 불과할까요? zh-CN을 저장할 수 있을까요?

그 누구도 즉석에서 이 질문들에 답할 수 없습니다. 정답은 소스 코드, Git 히스토리, 그리고 3년 전 마이그레이션을 작성했던 사람의 희미해지는 기억 속에 흩어져 있습니다.

단 하나의 명령. 30초.

  npx schemalog generate
  npx schemalog dict

8개의 마이그레이션을 분석했습니다. 결과는 다음과 같습니다.

1. 마이그레이션 변경 로그 (Migration Changelog)

위험 수준(risk levels)이 포함된 모든 마이그레이션에 대한 사람이 읽을 수 있는 요약본입니다:

#	타임스탬프 (Timestamp)	변경 사항 (Change)	위험 수준 (Risk)
1	2015-09-15	포스트 생성 (Create posts)	🟢 안전 (safe)
2	2015-09-15	사용자 생성 (Create users)	🟢 안전 (safe)
3	2015-09-15	태그 및 posts_tags 생성 (Create tags + posts_tags)	🟢 안전 (safe)
4	2016-04-22	설정 및 시드 데이터 생성 (Create settings + seed data)	🟢 안전 (safe)
5	2019-05-22	멤버(구독) 생성 (Create members (subscriptions))	🟢 안전 (safe)
6	2020-06-15	Stripe 결제 및 구독 (Stripe payments + subscriptions)	🟢 안전 (safe)
7	2023-05-23	이메일 추적 시스템 (Email tracking system)	🟢 안전 (safe)
8	2025-07-22	10개의 지원 중단된 컬럼 삭제 (Drop 10 deprecated columns)	🔴 위험 (danger)

마지막 마이그레이션은 자동으로 빨간색 플래그가 지정됩니다. 5개의 테이블에 걸쳐 10개의 컬럼이 삭제되었습니다. 10년 된 프로젝트에서 이러한 종류의 변경 사항은 조용히 지나가서는 안 됩니다.

2. 마이그레이션별 분석 (Per-Migration Analysis)

  분석 중: 20250722191500_v6_cleanup_deprecated_fields.sql
    🔴 위험 (danger) — posts, users, tags, settings, members 테이블에서
                 지원 중단된 (deprecated) created_by 및 updated_by 컬럼을 삭제함,
...

단순히 무엇이 바뀌었는지가 아니라, 왜 바뀌었는지를 보여줍니다. AI는 SQL을 읽는 것만으로 created_by / updated_by가 Ghost 6.0의 액션 로그 (Action Log) 시스템으로 대체되었음을 추론합니다.

3. 전체 데이터 사전 (Complete Data Dictionary)

모든 테이블과 모든 컬럼에 대한 설명입니다. 여기는 posts 테이블입니다:

컬럼 (Column)	타입 (Type)	설명 (Description)
`id`	VARCHAR(24)	기본 키 (Primary key), 고유 식별자
`uuid`	VARCHAR(36)	범용 고유 식별자 (Universally unique identifier)
`title`	VARCHAR(2000)	포스트 제목
`slug`	VARCHAR(191)	URL 친화적인 제목 버전
`mobiledoc`	TEXT	Mobiledoc 리치 텍스트 (rich-text) 형식의 콘텐츠
`html`	TEXT	렌더링된 HTML 콘텐츠
`plaintext`	TEXT	콘텐츠의 일반 텍스트 (Plain text) 버전
`featured_image`	VARCHAR(2000)	대표 이미지 (featured image)의 URL
`featured`	TINYINT(1)	포스트의 대표 여부 (0/1)
`type`	VARCHAR(50)	`post` 또는 `page`
`status`	VARCHAR(50)	`draft`, `published`, `scheduled`
`visibility`	VARCHAR(50)	`public`, `members`, `paid`
`locale`	VARCHAR(6)	언어 코드: `en`, `zh-CN`
`author_id`	VARCHAR(24)	`users.id`를 참조하는 외래 키 (Foreign key)
`published_at`	DATETIME	포스트가 게시된 시점

12개의 테이블에 걸쳐 80개 이상의 컬럼이 존재합니다. 각각의 컬럼에 대해 AI가 추론한 설명, 타입 설명, 그리고 적용 가능한 경우 열거형 (enum) 값이 제공됩니다.

이것은 Ghost의 문제가 아닙니다. 당신의 문제입니다.

Ghost는 잘 설계된 프로젝트입니다. 하지만 아무리 뛰어난 프로젝트라도 데이터베이스 문서(database documentation)는 서서히 노후화됩니다.

당신의 프로젝트도 다르지 않습니다. 매 릴리스마다 migrations/ 디렉토리에 더 많은 .sql 파일이 추가됩니다. 3개월 후에는 다음과 같은 상황이 발생합니다:

user_status와 account_state의 차이점은 무엇인가?
legacy_score가 아직 어디에서 사용되고 있는가?
누가 그 DROP TABLE 명령을 실행했으며, 아무도 눈치채지 못했는가?

이것은 문서를 작성할 사람이 부족해서 생기는 문제가 아닙니다. 인간이 이 일을 해서는 안 됩니다.

SQL 마이그레이션 (migrations)은 이미 기계가 읽을 수 있는 형태입니다. 이를 인간이 읽을 수 있는 문서로 번역하는 것이야말로 바로 AI가 해야 할 일입니다.

Schemalog — 당신의 데이터베이스 문서가 더 이상 거짓말을 하지 않도록

  npm install -g schemalog

  cd your-project
...

지원되는 형식 (Supported formats): YYYYMMDD_description.sql 또는 YYYYMMDDHHMMSS_description.sql
Supabase, Drizzle, Flyway, raw SQL 등 타임스탬프가 찍힌 마이그레이션 (migration) 파일을 생성하는 모든 도구와 함께 사용할 수 있습니다.

AI 제공업체 (AI Providers): DeepSeek 또는 OpenAI (GPT-4o-mini). 일반적인 분석 비용은 1센트의 아주 적은 일부에 불과합니다.

증분 캐싱 (Incremental caching): 두 번째 실행 시 비용은 0입니다. 새로 추가되거나 변경된 마이그레이션만 AI를 호출합니다.

위험 감지 (Danger detection): DROP TABLE, DROP COLUMN, ALTER TYPE 명령어를 지연 시간(latency) 없이 로컬에서 즉시 감지하여 표시합니다.

GitHub Action: PR(Pull Request)에 .sql 마이그레이션이 포함되면 변경 로그(changelog)를 자동으로 댓글로 남깁니다. 이제 코드 리뷰 중에 마이그레이션 폴더를 일일이 뒤질 필요가 없습니다.

직접 시도해 보세요:

  npm install -g schemalog

npm: npmjs.com/package/schemalog

질문이나 피드백이 있으신가요? 아래에 댓글을 남겨주세요.

첫 번째 릴리스입니다. 모든 피드백을 환영합니다.