AI가 마음대로 정하던 DB 설계를 붙잡는 Claude Code·Codex 플러그인 ‘easy-rdbms’
AI 코딩 에이전트에게 앱을 맡기면 데이터베이스(DB) 설계도 에이전트가 알아서 정합니다. 테이블 이름, 기본 키의 타입, 금액 컬럼의 타입, 삭제할 때의 동작까지 그럴듯해 보이는 기본값을 고릅니다. easy-rdbms는 이 결정들을 처음부터 데이터베이스 엔지니어가 설계하는 방식으로 잡아 주는 Claude Code·Codex 플러그인입니다. DB 선택, 이름 규칙, 단계별 모델링, 스키마·쿼리·마이그레이션 리뷰를 맡습니다. 대상은 MySQL 8.4 LTS·PostgreSQL 18·SQLite 3.37 이상입니다. 코드는 GitHub에 MIT 라이선스로 공개했고 이 글은 0.6.0 기준입니다.
AI가 고른 기본값은 첫날에는 맞습니다
함수는 다시 짜면 되지만 스키마(테이블 구조)는 그렇지 않습니다. 행이 10억 개 쌓인 테이블의 기본 키를 바꾸려면 운영 배포를 사이에 낀 몇 주짜리 마이그레이션이 필요합니다. 에이전트가 자주 고르는 기본값은 첫날에는 모두 맞고 1년쯤 지나면 비싸집니다.
| AI 기본값 → 플러그인 | 기본값의 문제 |
|---|---|
SERIAL → bigint |
초당 1만 건이면 약 2.5일 만에 번호가 바닥남 |
users → member |
단수형으로 바꾼 user는 PostgreSQL 예약어 |
ON DELETE CASCADE → 명시적인 배치 삭제 |
계정 하나를 지우면 가장 큰 테이블을 트랜잭션 하나로 훑음 |
FLOAT → 통화에 맞춘 numeric |
반올림 오차로 청구서와 원장이 어긋남 |
예를 들어 메시지 테이블의 id를 SERIAL로 만들면 PostgreSQL int가 됩니다. int는 약 21억이 상한이고, 오래된 행을 지워도 한번 쓴 번호는 돌아오지 않습니다. 메시지처럼 행 수에 상한이 없는 테이블에는 처음부터 bigint를 씁니다. 플러그인의 이름 규칙은 테이블 이름을 단수형으로 쓰는데, users의 단수형인 user는 PostgreSQL 예약어라 쓸 때마다 따옴표로 감싸야 합니다. 나중에 이름을 바꾸면 모든 쿼리를 고쳐야 하므로 처음부터 member로 정합니다.
이 결정들은 테스트에서도 리뷰에서도 걸리지 않고 테이블이 이미 가득 찬 뒤에 드러납니다. 플러그인은 되돌리기 어려운 이런 결정을, 되돌리는 비용이 아직 0인 시점으로 앞당깁니다.
설치
Claude Code에서는 다음 두 줄로 설치합니다.
/plugin marketplace add TeiNam/easy-rdbms
/plugin install easy-rdbms@easy-rdbms
Codex에서는 이렇게 설치합니다.
codex plugin marketplace add TeiNam/easy-rdbms
codex plugin add easy-rdbms@easy-rdbms
Codex는 플러그인 훅(정해진 시점에 실행되는 스크립트)을 자동으로 신뢰하지 않습니다. 설치한 뒤 /hooks에서 Easy RDBMS의 SessionStart 훅을 확인하고 신뢰해야 DB 엔진 자동 감지가 켜집니다. 업데이트는 Claude Code에서 /easy-rdbms:update, Codex에서 $easy-rdbms:update로 합니다.
무엇이 들어 있나요
스킬 9개가 들어 있고 Claude Code와 Codex가 같은 skills/ 디렉터리를 함께 씁니다. 스킬(skill)은 에이전트가 특정 작업을 할 때 꺼내 읽는 지침 묶음입니다. 작업 내용이 스킬과 맞으면 자동으로 쓰이고 이름을 불러 직접 쓸 수도 있습니다.
| 스킬 | 쓰는 곳 |
|---|---|
db-select |
어떤 DB를 어떤 구성으로 쓸지, 3년 동안 얼마가 드는지 |
rdbms-modeling |
개념 → 논리 → 물리 설계, 단계 사이마다 확인 |
rdbms-review |
이미 있는 SQL·스키마·마이그레이션 리뷰 |
rdbms-naming |
테이블·컬럼·인덱스·제약 조건 이름과 데이터 타입 선택 |
mysql-guideline |
MySQL 8.4 LTS 이상, Aurora MySQL |
postgres-guideline |
PostgreSQL 18, 16/17 호환, 관리형·Aurora, FDW·PostGIS·pgvector |
sqlite-guideline |
SQLite 3.37 이상, 임베디드·로컬·프로토타입 |
database-migrations |
무중단 스키마 변경과 롤백 전략 |
update |
플러그인 업데이트와 설치 버전 확인 |
Claude Code에서는 /schema-design·/schema-review 명령과 rdbms-modeler·rdbms-reviewer 서브에이전트(메인 에이전트가 맡긴 작업을 따로 처리하는 보조 에이전트)도 쓸 수 있습니다. 명령과 서브에이전트 모두 스킬을 부르는 얇은 껍데기라 규칙을 따로 들고 있지 않습니다. Codex는 사용자 정의 슬래시 명령과 이름 붙은 서브에이전트를 등록할 수 없어서 $easy-rdbms:rdbms-modeling처럼 스킬 이름으로 같은 절차를 부릅니다.
설계는 개념 → 논리 → 물리 순서로 합니다
rdbms-modeling은 요구사항을 받자마자 DDL(테이블을 만드는 SQL)로 넘어가지 않습니다. 세 단계를 거치고 단계가 끝날 때마다 사용자에게 확인을 받습니다.
- 개념 단계에서는 업무 개념과 관계, 사용자가 쓰는 용어만 다룹니다. 컬럼·타입·키·DB 제품은 아직 나오지 않습니다. 빠진 개념이나 잘못 붙은 이름이 없는지, 상태가 어떻게 바뀌는지, 무엇이 무엇에 속하는지, 이력을 남겨야 하는지를 묻고 답을 기다립니다.
- 논리 단계에서는 엔터티·속성·기본 키·외래 키·관계의 수를 일반 타입으로 정합니다. 기본은 제3정규형(3NF)이고 모든 엔터티에 보이스-코드 정규형(BCNF) 위반이 없는지도 검사합니다. 정규형은 같은 사실이 여러 곳에 중복 저장되지 않도록 테이블을 나누는 기준입니다. 이 단계의 확인에서는 ‘종류’로 나눈 것이 사실은 시간이 지나면 바뀌는 ‘상태’가 아닌지를 특히 묻습니다.
- 물리 단계는 대상 DB가 확정되어야 시작합니다. DB가 정해지지 않았으면 대신 고르지 않고
db-select로 넘깁니다. 엔진이 정해지면 그 엔진의 DDL을 씁니다.
엄격함은 다루는 데이터에 따라 달라집니다. 결제·재고·권한·계약·원장·감사처럼 틀리면 안 되는 영역은 세 단계를 모두 거치고 단계마다 확인합니다. 일반 기능은 1·2단계를 짧게 하고 개인 도구는 1·2단계를 합칠 수 있습니다. 합칠 때는 합쳤다고 밝히고 단계를 말없이 건너뛰지 않습니다.
세션을 열면 DB 엔진부터 알아봅니다
세션이 시작될 때 SessionStart 훅이 프로젝트의 docker-compose.yml·.env·prisma/schema.prisma·package.json·requirements.txt·go.mod 같은 파일을 읽어 어떤 DB를 쓰는지 찾습니다. 드라이버 이름이나 접속 문자열로 PostgreSQL·MySQL·MariaDB·SQLite를 가려내고 rds.amazonaws.com이나 supabase 같은 흔적이 있으면 배포 형태도 함께 알려 줍니다. 엔진이 하나로 정해지면 에이전트가 같은 질문을 다시 하지 않고 버전과 배포 형태만 확인합니다. 아무것도 찾지 못하면 아무 말도 하지 않습니다.
리뷰는 심각도 순서로 보여 줍니다
rdbms-review는 먼저 엔진과 버전을 확정합니다. DB에 접속할 수 없으면 확인용 쿼리만 건네고 그 결과에 기대는 항목은 unverified로 표시합니다. 그다음 정확성과 동시성, 쿼리 성능, 스키마 설계, 보안, 운영 순서로 봅니다. 결과에는 요약 대신 CRITICAL·HIGH·MEDIUM 심각도 순으로 파일과 줄, 결함, 영향, 고치는 방법을 적습니다. 문제가 없으면 없다고 한 줄로 말하고 지적거리를 지어내지 않습니다.
같은 앱을 두 번 설계해 보면
저장소의 같은 앱을 두 번 설계한 비교 문서는 AI 채팅 앱의 PostgreSQL 스키마를 플러그인 없이 한 번, 플러그인을 쓰고 한 번 설계해 나란히 놓습니다. 이 앱에는 가입·대화·메시지·토큰 단위 과금이 있습니다. 플러그인 없이 만든 쪽은 users·conversations·messages·usage 네 테이블에 SERIAL·CASCADE·FLOAT를 씁니다. 플러그인을 쓴 쪽은 스키마를 app과 log로 나누고, 메시지 테이블을 bigint 키와 월별 파티션으로 만들고, 사용량을 numeric(19,6)으로 집계합니다. 문서는 이 결과를 “더 길고, 오는 길에 질문을 더 많이 했다”고 정리합니다.
문서는 두 설계의 차이 11가지를 비용과 함께 적습니다. 그중 몇 가지만 옮깁니다.
messages.id를int로 잡으면 초당 100건만 들어와도 약 8개월이면 번호가 바닥납니다. 고치려면 테이블 전체를 다시 쓰고 모든 인덱스와 참조 컬럼을 함께 옮겨야 해서 몇 주가 걸립니다.messages.conversation_id에 인덱스가 없으면 메시지가 10만 건쯤 쌓일 때부터 느려지고 그때는 이미 커진 테이블에CREATE INDEX CONCURRENTLY를 걸어야 합니다.- 삭제 플래그만 두면 감사 기록이 되지 않습니다. 남기지 않은 이력은 나중에 되살릴 수 없습니다.
문서의 마지막 문장은 이 플러그인이 하는 일을 요약합니다. 플러그인이 스키마를 빠르게 만들지는 않지만 되돌릴 수 없는 몇 가지 결정을 되돌리는 비용이 0인 유일한 시점에 막아 준다는 것입니다.
구조적 비용은 근거 없이 지불하지 않습니다
플러그인 전체에 적용되는 원칙은 하나입니다. 구조를 복잡하게 만드는 결정에는 근거가 있어야 합니다. 비정규화에는 측정값이, 파티셔닝에는 그 테이블을 쓰는 쿼리와 보관 정책 코드가, 인덱스에는 실행 계획이 있어야 합니다. 근거가 없으면 needs measurement로 남깁니다.
DB 선택도 같습니다. db-select는 지금 규모에 맞는 구성을 고르고 월 요금 대신 3년 총비용으로 비교합니다. 무료 DB도 운영할 사람의 인건비가 가장 큰 항목이라 공짜가 아닙니다. 옮기는 비용이 3년 동안 아끼는 돈보다 크면 지금 쓰는 DB를 유지하는 것도 후보가 됩니다. 실제 가격을 모르면 낮음·중간·높음 등급으로 표시하고 그렇게 했다고 밝힙니다.
문서 속 예제는 실제 DB에서 돌려 봅니다
스킬 문서에 들어 있는 SQL 예제는 CI(지속적 통합)에서 일회용 PostgreSQL 16·18과 MySQL 8.4 컨테이너에서 실제로 실행합니다. PostgreSQL 18에서는 PostGIS와 pgvector 확장까지 설치해 돌립니다. 비교 문서의 ‘플러그인을 쓴 쪽’ DDL도 그대로 실행해 잘못된 값을 넣으면 체크 제약이 실제로 거부하는지 확인합니다. DB 감지 훅은 32가지 경우로 시험합니다.
모델별 동작도 시험했습니다. 2026년 11월 3일, PostgreSQL 18 마이그레이션과 앱 코드에 결함 11개를 심었습니다. 이 코드의 리뷰를 Claude Haiku·Sonnet·Opus에 플러그인을 켠 채로 맡기고 Opus에는 플러그인 없이도 한 번 더 맡겼습니다. 네 번 모두 11개를 다 찾았습니다. 차이는 처방에서 났습니다. 플러그인 없이 리뷰한 Opus는 이력 테이블로 걸린 ON DELETE CASCADE를 MEDIUM으로 보고 RESTRICT를 제안했는데, 이렇게 하면 주문을 지울 수 없게 되어 이력 정책과 충돌합니다. 결함을 찾는 능력은 같았고 결과를 가른 것은 정책이었습니다.
생각: AI가 마음대로 정하는 DB 설계 때문에 만들었습니다
여기서부터는 플러그인을 만든 사람으로서 하는 개인적인 이야기입니다.
바이브 코딩을 하는 사람들이 늘어나는데, DB 설계나 구성은 AI가 마음대로 하기 때문에 이 플러그인을 만들었습니다. 앱 코드는 나중에 고쳐도 되지만 데이터베이스는 한번 데이터가 쌓이면 바꾸기 어렵습니다. 그래서 그 결정만큼은 처음에 제대로 하도록 돕는 도구가 필요하다고 생각했습니다.