Claude Code로 데이터베이스 스키마와 쿼리 설계하기: 실전 가이드 (2026)

Claude Code가 정말로 DB를 설계하고 쿼리를 작성할 수 있을까요?

네, 그것도 아주 잘해요. 스키마 설계와 쿼리 작성이야말로 Claude Code 같은 에이전트형 도구가 만들어진 목적에 딱 맞는 작업이거든요. Claude Code는 단순한 자동완성 제안이 아니에요. 여러분의 파일과 리포지토리 전체를 읽고, 터미널에서 명령(psql, mongosh, 테스트 실행)을 돌리고, 그 출력을 읽고, 스스로 고치며 반복할 수 있어요. 데이터베이스에서는 이 "컨텍스트를 읽고 → DDL/쿼리를 생성하고 → 실행하고 → 결과를 읽고 → 조정하는" 루프가 Claude Code가 가장 강력한 지점이에요.

이 가이드는 가장 흔한 두 시스템, PostgreSQL(관계형)과 MongoDB(문서형)에 초점을 맞춰요. 같은 접근 방식이 둘 다에 통해요. 이제 막 시작해서 Claude Code가 무엇인지 아직 잘 모른다면, 먼저 Claude Code란 무엇이고 무엇에 쓰는지를 읽고 여기로 돌아오세요.

먼저 솔직한 주의점 하나. AI는 데이터베이스 작업이 빠르지만 자동으로 안전한 건 아니에요. 존재하지 않는 컬럼 이름을 지어내거나, 금액에 잘못된 데이터 타입을 고르거나, 되돌릴 방법이 없는 마이그레이션을 생성할 수 있어요. 그래서 이 가이드 전체는 두 가지 원칙 위에 서 있어요. 프로덕션에는 읽기 전용 접근만 허용하기, 그리고 Claude에게 항상 자기 작업을 확인할 방법을 주기예요. 연결 → 스키마 설계 → 쿼리 작성 → 인덱스와 성능 → 마이그레이션의 전체 루프를 따라가 볼게요.

설정: Claude Code를 데이터베이스에 연결하기

Claude에게 무언가를 시키기 전에, 먼저 데이터를 실제로 "볼" 수 있게 해줘야 해요. 가장 안전한 것부터 가장 유연한 것까지 세 가지 방법이 있어요.

방법 1 - MCP 서버(권장, 읽기 전용)

MCP(Model Context Protocol)는 Claude Code가 데이터베이스를 포함한 외부 도구에 연결하는 표준 방식이에요. Claude Code MCP 문서에는 "우리 PostgreSQL 데이터베이스를 기반으로" 데이터를 조회하는 직접적인 예시가 나와요(Claude Code MCP 문서, Anthropic, 2026). HTTP MCP 서버를 추가하는 명령은 다음과 같아요.

claude mcp add --transport http postgres-db https://your-mcp-endpoint

안전과 관련해 결정적으로 중요한 점. 레퍼런스 Postgres MCP 서버는 "스키마 검사 기능이 있는 읽기 전용 데이터베이스 접근"으로 설명돼요. 즉 구조를 읽고 검사만 할 뿐, 쓰기는 하지 않아요(modelcontextprotocol/servers, 2026. 이 서버는 이후 servers-archived 리포지토리로 옮겨졌어요). AI를 DB 가까이 둘 때 바로 이런 형태가 이상적이에요. 컨텍스트를 이해하려고 스키마를 읽을 수는 있어도, 스스로 테이블을 삭제할 수는 없으니까요. MCP가 처음이라면 MCP란 무엇이고 외부 도구를 Claude Code에 연결하는 방법을 보세요.

방법 2 - psql / mongosh CLI

더 간단하게는, 터미널을 통해 Claude에게 명령을 실행하게 하면 돼요. 이미 psql이나 mongosh가 설정돼 있다면 Claude가 직접 호출할 수 있어요. 유연하지만(쓰기 명령도 실행할 수 있어요) 바로 그 이유로 더 위험해요. 개발용/로컬 DB에만 연결하고, 쓰기 권한이 있는 프로덕션 연결 문자열에는 절대 연결하지 마세요.

방법 3 - @로 스키마 파일 넘기기

실제 DB에 연결할 준비가 아직 안 됐다면, @ 문법으로 schema.sql 파일이나 테이블 설명을 Claude에게 넘기기만 하면 돼요.

Read @db/schema.sql and summarize the tables, primary keys, and relationships.
Then list 3 design risks you see.

1단계 - Claude Code로 스키마 설계하기

가장 흔한 실수는 Claude를 열자마자 "users 테이블 만들어줘"라고 입력하는 거예요. 그러면 AI가 대충 추측한 일반적인 스키마가 돌아와요. 올바른 방법은 워크로드 우선이에요. 먼저 부하의 유형을 정하고, 그다음에 AI가 테이블을 만들게 하세요.

먼저 워크로드를 분류하세요

이게 어떤 종류의 애플리케이션인지 스스로 묻고 Claude에게도 알려주세요. 유형마다 최적화하는 데이터 형태가 다르니까요.

플랜 모드를 써서 쓰기 전에 읽게 하세요

플랜 모드를 켜고(Shift+Tab을 눌러 모드를 전환해요) 요구사항을 읽고, 불분명한 점이 있으면 질문하고, 그다음에야 DDL을 생성하도록 Claude에게 요청하세요. 이렇게 하면 잘못된 가정으로 성급하게 테이블을 만드는 것을 막을 수 있어요.

프롬프트 패턴: 컬럼이 아니라 불변 조건을 말하세요

컬럼을 나열하는 대신 불변의 비즈니스 규칙을 설명하세요. 그러면 AI가 스스로 적절한 기본 키, 고유 제약, 외래 키를 설정해요.

Design a PostgreSQL schema for a small shop. Workload: OLTP.
Invariants:
- One email belongs to exactly one account (unique).
- An order must belong to an existing user (an orphan = a bug).
- Each order_items row records the price AT PURCHASE TIME, not the current price.
- Money must be exact, with no rounding error.
Ask me questions if anything is missing before writing the DDL.

관계형 체크리스트(Claude가 생성한 DDL을 검토하기 위해)

• 엔터티는 명사로 이름 짓고, 조인 테이블은 그것이 나타내는 관계를 따라 이름 지어요.
• 안정적인 식별자는 기본 키에, 고유한 비즈니스 규칙은 고유 제약에 넣어요.
• 고아 데이터가 버그가 되는 경우에는 항상 외래 키를 쓰세요.
• 금액, 수량, 시간은 정확한 타입을 쓰세요. 금액에 float는 절대 쓰지 마세요(numeric/decimal을 쓰세요).
• 다대다: 전용 조인 테이블을 만들고 유용한 메타데이터 컬럼을 추가해요.
• 인덱스는 필요하다고 증명한 술어에 대해서만 추가하세요(모든 것에 인덱스를 걸지 마세요).

실제 예시로, Claude가 만든 최소한의 이커머스 스키마예요(제가 한 줄 고쳤어요. 아래 메모 참고).

CREATE TABLE users (
 id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 email text NOT NULL UNIQUE,
 created_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE orders (
 id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 user_id bigint NOT NULL REFERENCES users(id),
 status text NOT NULL DEFAULT 'pending',
 created_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE order_items (
 id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 order_id bigint NOT NULL REFERENCES orders(id),
 product_id bigint NOT NULL,
 quantity int NOT NULL CHECK (quantity > 0),
 unit_price numeric(12,2) NOT NULL -- NOT float: money must be exact
);

처음에 Claude는 unit_price를 real(부동소수점)로 남겨뒀어요. 저는 그걸 numeric(12,2)로 바꾸게 했어요. 이건 여러분이 직접 주의해야 하는 버그의 전형이에요. AI가 이걸 항상 기억하는 건 아니거든요.

PostgreSQL이냐 MongoDB냐? 접근 패턴으로 고르세요

취향으로 고르지 말고, 데이터가 어떻게 읽고 쓰이는지로 고르세요. 간단한 표예요.

임베딩과 참조 사이에서 고민될 때의 MongoDB 황금률이에요.

• 임베딩(Embed): 자식 데이터가 부모와 함께 읽고 쓰이고 또한 크기가 유한할 때(예: 주문 안의 배송 주소).
• 참조(Reference): 데이터가 무한정 늘어나거나, 여러 부모가 공유하거나, 자체 생명주기가 필요할 때(예: 화제가 된 게시물의 댓글).

2단계 - Claude Code로 쿼리 작성하고 최적화하기

바로 여기서 Claude Code가 빛나요. 원하는 결과를 평이한 말로 설명하면, 쿼리를 작성하고 설명한 다음 최적화해줘요. SQL에서는 JOIN, 서브쿼리, CTE, 윈도우 함수를 자유자재로 다뤄요. MongoDB에서는 집계 파이프라인($match → $group → $lookup)을 구성해요.

실제 예시로 월별 매출 리포트를 볼게요. 프롬프트예요.

Write a Postgres query for total revenue per month in 2026,
counting only orders with status = 'paid'. Use a CTE for readability,
with a short explanation.

Claude의 응답이에요.

WITH paid_items AS (
 SELECT o.created_at, oi.quantity * oi.unit_price AS line_total
 FROM orders o
 JOIN order_items oi ON oi.order_id = o.id
 WHERE o.status = 'paid'
 AND o.created_at >= '2026-01-01'
 AND o.created_at < '2027-01-01'
)
SELECT date_trunc('month', created_at) AS month,
 SUM(line_total) AS revenue
FROM paid_items
GROUP BY 1
ORDER BY 1;

실행 결과(샘플 데이터)예요.

 month | revenue
--------------------+-----------
 2026-01-01 00:00:00 | 154200.00
 2026-02-01 00:00:00 | 187650.50
 2026-03-01 00:00:00 | 203110.00

MongoDB에서도 같은 아이디어가 파이프라인이 돼요. $match로 paid 주문을 거르고, $unwind로 아이템 배열을 펼치고, $group으로 월별로 묶어요. Claude에게 이걸 작성하게 하고 각 단계를 설명하게 하세요. 쿼리와 그 이해를 동시에 얻는 가장 빠른 방법이에요.

중요한 경고: Claude가 작성한 쿼리를 실제 데이터에 실행하기 전에 항상 다시 읽어보세요. WHERE가 빠진 UPDATE/DELETE는(AI가 실수로 만들어낼 수 있어요) 테이블 전체를 날려버릴 수 있어요. 읽고, 이해하고, 그다음 Enter를 누르세요.

3단계 - EXPLAIN ANALYZE로 인덱스와 성능 다루기

쿼리가 올바르게 도는 것만으로는 부족하고, 빠르게 돌아야 해요. Claude에게 EXPLAIN ANALYZE(Postgres)나 .explain()(Mongo)을 실행하게 하고, 실행 계획을 읽은 뒤, 맹목적으로가 아니라 적절한 위치에 인덱스를 제안하게 하세요.

Run EXPLAIN ANALYZE for the revenue query above.
If you see a Seq Scan on orders, suggest a suitable index and explain why.

큰 orders 테이블에서는 status와 created_at으로 거르기 때문에 초기 계획이 종종 Seq Scan을 보여줘요. 적절한 인덱스를 추가하세요.

CREATE INDEX idx_orders_status_created
 ON orders (status, created_at);

다시 실행하면 계획이 Index Scan으로 바뀌고, 쿼리 시간이 눈에 띄게 줄어요. Claude의 도움이 필요한 지점은 복합 인덱스의 컬럼 순서를 술어에 맞게 고르는 부분이에요. 여기가 초보 개발자들이 자주 틀리는 곳이거든요.

과도한 인덱싱(Claude 자신도 지나치게 하는 경향이 있어요)을 피하는 인덱싱 원칙이에요. 인덱스는 외래 키, 자주 거르거나 정렬하는 컬럼, 고유 제약에만 거세요. 인덱스를 하나 추가할 때마다 쓰기가 느려지고 저장 공간을 써요. 그러니 "혹시 몰라서" 인덱스를 걸지 마세요. Claude에게 "더 빠르게 인덱스를 추가해"라고 하면 과하게 하는 경향이 있어요. 증명 가능한 술어가 있는 인덱스만 제안하도록 요청하세요.

4단계 - Claude Code로 안전하게 마이그레이션하기

운영 중인 시스템에서 스키마를 바꾸는 일은 존재하는 작업 중 가장 사고가 나기 쉬운 작업이에요. Claude에게 마이그레이션을 생성하게 할 때의 안전한 절차예요.

1. 항상 롤백을 포함하세요. 모든 "up" 마이그레이션에는 짝이 되는 "down"이 있어야 해요. Claude에게 둘 다 작성하고 변경을 어떻게 되돌리는지 설명하게 하세요.
2. 먼저 사본에서 테스트하세요. 마이그레이션은 개발용 DB나 프로덕션 스냅샷에서 실행하고, 프로덕션에 바로 적용하지 마세요.
3. 전후를 비교하세요. 실행 전후로 행 수를 세고 샘플 레코드 몇 개를 확인해서 데이터가 유실되지 않았는지 확인하세요.
4. 서브에이전트로 diff를 검토하세요. 서브에이전트가 독립적인 PR처럼 마이그레이션을 검토하게 해서, 안전 장치가 없는 파괴적 작업(DROP, 데이터 타입 변경)을 찾게 하세요.

Anthropic의 모범 사례는 이 원칙을 한 줄로 요약해요. "Claude에게 자기 작업을 검증할 방법을 주라"(Claude Code 모범 사례, Anthropic, 2026). 데이터베이스에서 "검증"은 구체적인 걸 뜻해요. 테스트를 실행하고, EXPLAIN을 실행하고, 전후 행 수를 비교하는 것. AI가 "끝났다"고 하는 말을 곧이곧대로 믿지 않는 것이에요.

마련해둘 가치가 있는 가드레일이에요. 권한 훅을 사용해 Claude가 스스로 migrations/ 디렉터리에 쓰는 것을 막거나 파괴적인 DDL 명령을 차단해서, 모든 변경이 반드시 여러분의 검토를 거치게 하세요. 권한을 안전하게 조이는 방법은 Claude Code로 보안 감사 실행하기를 보세요.

AI에게 데이터베이스를 맡길 때의 진짜 함정들(프로덕션 전에 읽으세요)

이 섹션이 가장 중요한데, 거의 어떤 문서도 대놓고 말하지 않아요. AI는 DB 작업이 빠르지만, 정말로 틀리는 지점은 여기예요. 저는 이걸 전부 겪어봤어요.

• 컬럼/테이블 이름 지어내기. Claude는 스키마를 추측해서 존재하지 않는 컬럼을 참조할 때가 있어요. 쿼리를 쓰기 전에 항상 실제 스키마를(MCP나 @schema.sql로) 읽게 하세요.
• 금액에 잘못된 타입. 가격에 float/real을 쓰려는 경우가 아주 많아서 반올림 오차가 쌓여요. numeric/decimal을 필수로 하세요.
• 과도한 인덱싱. 여기저기 인덱스를 뿌리면 읽기를 의미 있게 빠르게 하지 못한 채 쓰기만 느려져요.
• 롤백 없는 마이그레이션. up은 생성하지만 down을 잊어서, 되돌려야 할 때 발이 묶여요.
• N+1 또는 풀 스캔 쿼리. JOIN 하나 대신 레코드마다 조회하는 루프를 쓰거나, 필터 조건을 빠뜨려요.

타협 불가능한 세 가지 규칙이에요. (1) 프로덕션에는 읽기 전용 접근만 허용. AI에게 읽게는 해도 절대 쓰게는 하지 마세요. (2) 모든 스키마 변경은 PR + 테스트를 거침. 직접 적용하지 마세요. (3) EXPLAIN + 행 수 비교로 검증. "끝났다"를 믿지 마세요. 이 세 가지만 지키면 DB에 AI를 쓰는 건 충분히 안전해요.

ak-databases 스킬(AgentKit)로 더 빠르게

"워크로드 우선, 불변 조건 명시, 체크리스트 포함" 프롬프트를 매번 다시 쓰고 있는 자신을 발견한다면, 솔직한 지름길이 있어요. AgentKit Engineer Kit(ak-databases 스킬 포함)는 바로 이 글의 뼈대를 패키지로 만든 거예요. ak-databases 스킬은 OLTP/OLAP 스키마 설계, Postgres/Mongo 쿼리 작성, 집계, 인덱싱, 마이그레이션을 다루고, db_migrate.py, db_backup.py, db_performance_check.py 같은 스크립트도 함께 와요. "…스키마를 설계해줘"처럼 자연스럽게 입력만 하면 스킬이 스스로 활성화되니, 프롬프트 패턴을 외울 필요가 없어요.

자주 묻는 질문(FAQ)

Claude Code가 데이터베이스에 직접 연결할 수 있나요?

네, 두 가지 방법이 있어요. MCP 서버(권장, 보통 읽기 전용)이거나, 터미널을 통해 Claude에게 psql/mongosh 명령을 실행하게 하는 방법이에요. 실제 DB에 아직 연결하고 싶지 않다면 @ 문법으로 스키마 파일을 붙여넣을 수 있어요.

Claude Code가 스스로 프로덕션에 쿼리를 실행하나요?

그런 능력을 줘서는 안 돼요. 프로덕션에는 읽기 전용 연결만 허용하고, 모든 쓰기/DDL 작업은 개발용 DB나 검토된 PR 뒤에 두세요. 파괴적인 명령을 차단하려면 권한 훅을 쓰세요.

PostgreSQL과 MongoDB 중 무엇을 골라야 하나요?

취향이 아니라 접근 패턴으로 고르세요. 엄격한 제약이 필요한 트랜잭션과 집계 리포팅에는 PostgreSQL, 하나의 단위로 읽고 쓰는 중첩 데이터에는 MongoDB예요. 금액 트랜잭션은 거의 항상 PostgreSQL이어야 해요.

Claude Code가 마이그레이션을 작성할 수 있나요?

네, 하지만 롤백 단계(down)도 작성하게 요청하고, 먼저 사본에서 테스트하고, 실행 전후 행 수를 비교해야 해요. AI가 생성한 마이그레이션을 프로덕션에 곧바로 적용하지 마세요.

AI에게 데이터베이스를 맡겨도 안전한가요?

세 가지 규칙을 지키면 안전해요. 프로덕션은 읽기 전용, 모든 변경은 PR + 테스트를 거침, 그리고 EXPLAIN ANALYZE + 행 수 비교로 검증. 진짜 위험은 쓰기 권한을 주고 확인 없이 AI를 믿는 데서 와요.

Engineer Kit을 꼭 사야 하나요?

아니요. 이 글의 워크플로 전체는 순수 Claude Code로 동작해요. ak-databases 스킬은 DB 작업을 정기적으로 하거나 팀으로 할 때 그걸 더 빠르고 일관되게 만들어줄 뿐이에요.

마무리와 다음 단계

네 단계를 정리해볼게요. DB에 연결하고(읽기 전용 MCP를 선호) → 워크로드로 스키마를 설계하고 → 검증하면서 쿼리를 작성하고 최적화하고 → 롤백과 함께 마이그레이션하기. 핵심은 AI에게 모든 걸 대신 시키는 게 아니라, 충분한 컨텍스트와 항상 자기 작업을 확인할 방법을 주는 거예요. 스키마가 끝나면 다음의 논리적 단계는 DB를 API 계층에 연결하는 거예요. Claude Code로 백엔드와 API 구축하기를 보세요. 그리고 DB 설계 부분을 더 빠르게 하고 싶다면 Engineer Kit의 ak-databases 스킬을 사용해보세요.