Claude Code나 Cursor에 테이블 구조를 설명하면 몇 초 만에 PostgreSQL 스키마가 나옵니다. 실행도 잘 되고 테스트도 통과하죠. 그런데 6개월 뒤, 화폐 계산 버그를 고치고 타임존 문제를 추적하며 마이그레이션을 다시 작성하는 자신을 발견하게 됩니다. AI가 만든 코드는 작동했지만 좋은 코드는 아니었던 거죠.
PostgreSQL 전문 기업 Timescale이 AI 코딩 도구의 코드 품질 문제를 해결하는 오픈소스 도구 pg-aiguide를 공개했습니다. AI가 PostgreSQL, MySQL, SQLite 등 모든 데이터베이스 코드를 섞어 학습하면서 PostgreSQL 특유의 베스트 프랙티스를 놓치는 구조적 문제를 지적하고, 이를 해결하기 위한 구체적인 방법을 제시합니다.
출처: We Taught AI to Write Real Postgres Code (And Open Sourced It) – Tiger Data
작동하지만 좋지 않은 코드의 문제
AI가 생성한 PostgreSQL 스키마는 겉으로 보기엔 괜찮습니다. 그런데 자세히 들여다보면 조용한 재앙들이 숨어 있죠. 가격에 money 타입을 쓰고, 랜덤 데이터에 BRIN 인덱스를 걸고, SERIAL과 UUID를 섞어 쓰고, timestamp without time zone을 사용합니다.
문제는 이런 선택이 당장은 티가 나지 않는다는 점입니다. 하지만 시간이 지나면서 화폐 변환 버그, 타임존 이슈, 성능 문제로 나타나죠. 데이터베이스 스키마는 나중에 바꾸기가 정말 어렵습니다. 애플리케이션 코드는 리팩토링하면 되지만, 데이터가 쌓인 상태를 변경하려면 신중한 마이그레이션 계획이 필요하거든요.
2024 State of Postgres 조사에 따르면 PostgreSQL 개발자의 AI 도구 사용률이 1년 만에 37%에서 55%로 급증했습니다. 그런데 METR 연구에서는 경험 많은 개발자가 AI를 사용했을 때 오히려 작업 시간이 19% 더 걸렸다고 합니다. AI가 실패해서가 아니라 “거의 맞는” 출력을 만들어냈기 때문이죠. 이런 미묘한 실수를 찾아내고 고치는 데 시간이 가장 많이 걸립니다.
AI는 왜 나쁜 PostgreSQL 코드를 만들까
근본 원인은 학습 데이터에 있습니다. AI는 인터넷 전체에서 SQL을 배웠어요. PostgreSQL뿐 아니라 MySQL, SQLite, SQL Server, Oracle, 각종 튜토리얼, 10년치 Stack Overflow 답변까지 모두 섞여 있죠. 이 엄청난 노이즈 속에서 PostgreSQL 특유의 관용적이고 고품질인 패턴은 묻혀버립니다.
예를 들어 PostgreSQL은 외래키 컬럼에 자동으로 인덱스를 만들지 않습니다. MySQL 개발자에게는 낯선 동작이죠. 또 길이 제한을 넘는 데이터를 삽입하면 자동으로 잘라내지 않고 에러를 냅니다. NUMERIC(2,0) 컬럼에 999를 넣으면 실패합니다. 이런 PostgreSQL만의 “gotcha”들을 AI는 제대로 학습하지 못했어요.
pg-aiguide의 해법: Skills와 버전별 문서 검색
pg-aiguide는 세 가지 요소로 AI에게 PostgreSQL 판단력을 제공합니다.
첫째, AI 최적화 Skills입니다. 단순한 튜토리얼이 아니라 기계가 바로 적용할 수 있는 밀도 높은 가이드예요. “BIGINT GENERATED ALWAYS AS IDENTITY를 쓰세요”, “money 타입 쓰지 마세요”, “timestamp는 반드시 timezone과 함께”, “외래키에 인덱스 추가하세요” 같은 구체적이고 단호한 지침이 담겨 있습니다.
둘째, 버전별 공식 문서 시맨틱 검색입니다. PostgreSQL 15~18 버전별로 정확한 문서를 가져옵니다. 이게 중요한 이유는 버전마다 기능이 다르기 때문이죠. Postgres 15의 UNIQUE NULLS NOT DISTINCT, Postgres 16의 병렬 쿼리 개선, Postgres 17의 COPY 에러 처리 등 없는 기능을 환각으로 만들어내는 걸 막아줍니다.
셋째, 확장 생태계 문서로 시작은 TimescaleDB이고 빠르게 확장 중입니다.
모든 문서는 PostgreSQL 자체에 청크로 나뉘어 저장되며, 헤더 컨텍스트와 소스 URL을 유지해 각 조각이 전체 맥락에서 어떤 의미인지 알 수 있게 되어 있습니다.
코드로 보는 차이
같은 서점 스키마 설계를 요청했을 때 결과를 비교해보죠.
pg-aiguide 없이:
CREATE TABLE customers (
customer_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
...
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
...
);
CREATE TABLE authors (
author_id SERIAL PRIMARY KEY,
...
);작동하지만 문제가 많습니다. UUID와 SERIAL을 섞어 쓰고, VARCHAR에 임의의 길이 제한을 두고, 이메일 대소문자를 구분하며, CURRENT_TIMESTAMP는 시스템마다 다르게 동작할 수 있습니다.
pg-aiguide 사용:
CREATE TABLE authors (
author_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
name TEXT NOT NULL,
bio TEXT,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE users (
user_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
email TEXT NOT NULL UNIQUE,
...
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE UNIQUE INDEX ON users (LOWER(email));일관된 identity 컬럼, 불필요한 VARCHAR 대신 TEXT, 올바른 타임스탬프 처리(TIMESTAMPTZ + now()), 대소문자 무시 고유성 제약이 제대로 적용되었습니다.
이 변화는 사용자가 프롬프트를 바꾸거나 문서를 붙여넣을 필요 없이 자동으로 일어났습니다. AI가 design_postgres_table 스킬을 자동으로 찾아 적용한 결과죠.
MCP로 모든 AI 도구와 통합
pg-aiguide는 Model Context Protocol(MCP) 서버로 제공됩니다. Claude Code뿐 아니라 Cursor, Codex, Gemini CLI, VS Code, Windsurf 등 MCP 호환 도구 어디서나 사용할 수 있어요. 계정도 필요 없고 사용 제한도 없으며 완전 무료입니다.
Claude Code는 skills를 네이티브로 지원하기 때문에 플러그인으로 설치하면 view_skill 도구가 자동으로 비활성화되고 더 효율적으로 작동합니다.
Timescale팀은 인덱싱 가이드, 전문 검색 스킬, PostGIS와 pgvector 같은 필수 확장 문서를 추가하고 있습니다. 키워드 BM25 검색도 시맨틱 검색과 결합해 더 정확한 검색을 제공할 예정이고요. 하지만 팀만으로는 PostgreSQL 35년 역사 속 모든 지혜를 담을 수 없습니다.
오픈소스 프로젝트로 공개한 이유는 커뮤니티의 도움이 필요하기 때문입니다. 확장 문서 추가, 새로운 스킬 작성, 기존 스킬 개선, 파티셔닝이나 복제 같은 고급 주제 기여 등 여러 방식으로 참여할 수 있습니다. 특히 스킬이 중요한데요, 수년간의 경험을 AI가 즉시 활용할 수 있는 가이드로 바꾸는 작업이기 때문입니다.
AI 코딩 도구가 PostgreSQL을 “그냥 작동하는 수준”이 아니라 “전문가처럼” 다루게 만드는 여정에 함께하실 분들을 기다립니다.
참고자료:
답글 남기기