H0 Hackathon를 위해 구축한 AI 기반 데이터베이스 스키마 탐색기

다음 콘텐츠는 H0 Hackathon 참가를 목적으로 작성되었습니다. #H0Hackathon

당신은 새로운 프로젝트에 합류했습니다. 데이터베이스에는 30개의 테이블이 있습니다. 문서도 없습니다. ERD(Entity-Relationship Diagram)도 없습니다. 왜 status_v2_legacy가 존재하는지 기억하는 사람도 없습니다.

기존 도구들은 트레이드오프(tradeoff)를 강요합니다. pgAdmin은 원시 접근 권한(raw access)을 제공하지만 시각화 기능이 없습니다. dbdiagram.io는 스키마를 그릴 수 있게 해주지만, 마이그레이션(migration)이 일어날 때마다 수동 입력이 필요하며 데이터가 금방 오래된 것이 됩니다. SchemaSpy는 CLI 설정과 Java가 필요합니다. DBeaver는 데스크톱 전용입니다. 신입 사원에게 링크를 공유할 수 없습니다.

저는 스키마를 자동 발견(auto-discovers)하고, 시각화하며, 문서화하고, AI로 쿼리(query)할 수 있는 웹 도구를 찾아보았습니다. 이 네 가지를 모두 수행하는 도구는 찾을 수 없었습니다.

그래서 저는 H0 Hackathon를 위해 SchemaLens를 만들었습니다.

SchemaLens가 하는 일

PostgreSQL 연결 문자열(connection string)을 붙여넣으세요. 그게 전부입니다.

SchemaLens는 information_schema를 쿼리하여 테이블, 컬럼(column), 타입(type), 제약 조건(constraints), 외래 키(foreign keys), 그리고 행 추정치(row estimates)를 가져옵니다. 수동 입력도, DSL도, 설치도 필요 없습니다.

그 결과로 다음을 얻을 수 있습니다:

1. 대화형 ERD

실제 스키마로부터 자동으로 렌더링되는 완전한 엔티티 관계 다이어그램(Entity-Relationship Diagram)입니다. 확대, 이동이 가능하며, 어떤 테이블이든 클릭하여 타입, Null 허용 여부(nullability), 기본값(defaults), 제약 조건을 확인할 수 있습니다. 외래 키는 엣지(edges)로 표시됩니다. 다이어그램은 스스로 구축됩니다.

2. 스키마 건강 점수 (Schema Health Scoring)

10가지 자동화된 검사를 통해 알파벳 등급(A–F)과 함께 가중치가 적용된 점수를 산출합니다:

기본 키(Primary keys) 존재 여부
외래 키(Foreign key) 유효성
명명 규칙(Naming conventions)
컬럼 타입(Column types)
NOT NULL 제약 조건
타임스탬프(Timestamps)
과도하게 큰 컬럼(Oversized columns)
유니크 제약 조건(Unique constraints)
불리언(Boolean) 명명법
컬럼 개수(Column count)

각 발견 사항에는 심각도 수준(severity level)과 제안된 수정 방법이 포함됩니다.

3. AI 스키마 에이전트 (AI Schema Agent)

이것은 제가 가장 자랑스럽게 생각하는 기능입니다. 당신의 스키마를 이해하고 실제 데이터베이스에 대해 쿼리를 실행하는 AI 어시스턴트입니다.

일상적인 영어로 질문하세요:

"지난달에 가입한 모든 사용자를 보여줘"

에이전트는 쿼리를 작성하고, 검증하고, 실제 데이터베이스에서 실행하며, 결과를 테이블로 보여주고, 오류 발생 시 자동으로 재시도합니다.

도구 호출 파이프라인(tool-calling pipeline):

generate_sql → check_sql → execute_sql → retry loop

에이전트의 추론(reasoning), 도구 호출(tool calls), 그리고 결과가 실시간으로 스트리밍되는 것을 확인할 수 있습니다.

4. 공유 가능한 링크 (Shareable Links)

클릭 한 번으로 공개 URL이 생성됩니다. 팀원들은 별도의 가입 없이도 전체 ERD와 문서를 볼 수 있습니다.

보안 모델 (The Security Model)

이 부분이 가장 어려웠습니다. AI 에이전트가 라이브 데이터베이스를 대상으로 SQL을 생성하고 실행하기 때문입니다. 이는 매우 위험한 일입니다.

2단계 방어 체계:

애플리케이션 계층 (Application layer) — 정규 표현식(regex)을 통해 파괴적인 키워드(INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE)와 인젝션(injection) 시도를 차단합니다.
데이터베이스 계층 (Database layer) — PostgreSQL 자체를 READ ONLY 모드로 설정하여, 애플리케이션이 놓치는 어떤 쓰기 작업이라도 거부합니다.

설령 AI가 INSERT 문을 생성하더라도, PostgreSQL이 이를 거부합니다. 에이전트는 데이터를 쓸 수 없습니다.

이것은 단순히 AI에게 친절하게 행동하라고 지시하는 프롬프트(prompt)가 아니라, 심층 방어(defense in depth) 전략입니다.

구축 과정 (How I Built It)

계층 (Layer)	기술 (Technology)
프레임워크 (Framework)	Next.js 16, React, TypeScript
...

Aurora PostgreSQL이 핵심적인 역할을 수행합니다:

시스템 카탈로그(system catalog)로부터 스키마를 자동 탐색(Auto-discovers)
스키마 스냅샷을 JSONB로 저장
사용자 데이터, 세션, 채팅 기록 및 대화 관리
서버리스 스케일링 (Serverless scaling) — 항상 켜져 있는 서버가 필요 없음

Vercel + Aurora 조합은 정말 강력합니다. 단순히 해커톤을 위한 지름길이 아니라, 깔끔한 통합, 빠른 배포, 그리고 실제 확장 가능성을 갖춘 조합입니다.

직면했던 과제들 (Challenges I Hit)

Vercel에서 Aurora를 위한 SSL 설정

Aurora는 SSL을 요구하지만, 데이터베이스 드라이버가 자체 서명된 인증서(self-signed certs)를 거부합니다. 인증서 체인을 수락하도록 구성하기 전까지 커넥션 풀(connection pool)이 아무런 메시지 없이 실패했습니다. 소리 없는 실패(Silent failures)는 최악입니다.

Better-auth Drizzle 어댑터

테이블 키 명명 규칙의 불일치로 인해 인증 실패가 소리 없이 발생했습니다. 핸들러가 오류를 삼켜버리고 빈 응답을 반환했습니다. 실제 오류를 찾기 위해 핸들러의 출력값을 디버깅해야 했습니다.

AI 에이전트 SQL 안전성 (AI Agent SQL Safety)

실시간 스트리밍 환경에서 자기 수정형 재시도 루프 (self-correcting retry loop)를 안정적으로 작동하게 만드는 데 상당한 노력이 필요했습니다. AI가 유효하지 않은 SQL을 생성하면, 데이터베이스 오류를 읽고 쿼리를 수정한 뒤 자동으로 재시도합니다.

스키마 상태 튜닝 (Schema Health Tuning)

서류상으로 좋아 보이는 것(모든 테이블에 기본 키 (primary keys)가 있는지 확인하는 것)은 실제 스키마에서는 노이즈를 발생시킵니다. 각 검사 항목은 민감도 (sensitivity)와 특이도 (specificity) 사이의 균형을 맞추기 위해 반복적인 개선 과정이 필요했습니다.

배운 점

PostgreSQL의 시스템 카탈로그 (system catalog)는 매우 풍부합니다 — 데이터베이스는 이미 자신에 대한 모든 것을 알고 있습니다. 그저 물어보기만 하면 됩니다.
AI 에이전트에게는 프롬프트뿐만 아니라 가드레일 (guardrails)이 필요합니다 — 스키마 채팅이 작동하는 이유는 심층 방어 (defense in depth) 덕분입니다.
자기 수정형 에이전트에는 경계가 필요합니다 — 생성(generate) → 검증(validate) → 실행(execute) → 재시도(retry) 루프를 통해 에이전트가 스스로 실수를 바로잡을 수 있게 하지만, 명확한 재시도 제한 (retry limits)을 설정해야 합니다.
Vercel + Aurora는 프로덕션 환경에 적합합니다 — 단순히 해커톤을 위한 지름길이 아닙니다.

직접 체험해 보세요

schemalens-alpha.vercel.app으로 이동합니다.
"Connect database"를 클릭합니다.
PostgreSQL 연결 문자열 (connection string)을 붙여넣습니다 (Aurora, Railway, Supabase 등 모든 PostgreSQL DB가 작동합니다).
ERD가 자동으로 렌더링됩니다.
Schema Chat을 열고 다음을 시도해 보세요:
- "list all tables" (모든 테이블 목록 표시)
- "which tables have no foreign keys?" (외래 키가 없는 테이블은 무엇인가요?)
- "show me the 5 largest tables by row count" (행 수 기준으로 가장 큰 테이블 5개를 보여주세요)
- "if I delete a connector, which related data would be affected?" (커넥터를 삭제하면 어떤 관련 데이터가 영향을 받나요?)
"Share"를 클릭하여 공개 링크를 생성합니다.

향후 계획

스키마 차이 (Schema diff) — 변경 사항을 확인하기 위한 재-인트로스펙션 (re-introspect)
내보내기 (Export) — SQL 마이그레이션 (migrations), dbdiagram.io DSL, 마크다운 (markdown) 문서
팀 기능 — 공유 스키마 라이브러리, RBAC (역할 기반 액세스 제어), Slack 연동
멀티 데이터베이스 — MySQL, SQLite, MongoDB
스키마 모니터링 — 드리프트 (drift) 알림을 포함한 예정된 재-인트로스펙션

소스 코드

GitHub: github.com/faizalmy/schemalens

#H0Hackathon을 위해 ❤️를 담아 제작되었습니다. 플랫폼을 제공해 준 AWS Aurora와 Vercel에 감사드립니다.