[DB] ERD/스키마 문서 자동화, dbt는 왜 안 맞았나

배경

DB 변경을 고민하다가 "이참에 ERD·스키마 문서를 자동화해두면 좋지 않을까" 싶어서 도구를 찾아봤다. dbt를 한 번쯤 써보고 싶은 마음도 있어서 후보에 넣고 검토해봤는데, 결론적으로는 지금 프로젝트엔 안 맞는 도구였다.

dbt의 실제 역할

dbt는 데이터 웨어하우스(BigQuery, Snowflake, Redshift 등)에서 SQL 변환 모델을 관리하는 도구다. SELECT 기반 변환 쿼리를 .sql 파일로 작성하면 dbt가 실행 순서를 정리하고 테이블/뷰를 생성해준다. 주로 데이터 엔지니어·애널리스트가 쓰는 도구고, ERD 자동 생성이나 Django 모델 문서화와는 애초에 목적이 다르다.

지금 필요한 것(ERD·스키마 문서 동기화)에 맞는 도구들

도구 설치 하는 일 적합도

django-extensions + graphviz	pip install django-extensions	python manage.py graph_models → .dot/.png ERD 자동 생성	높음
SchemaSpy	jar 파일 실행	DB 직접 접속 → HTML ERD 자동 생성	중간 (DB 드라이버 필요)
dbdocs.io	외부 서비스	DBML 파일 작성 → 웹 ERD	중간 (수동 DBML 작성 필요)

dbt가 맞는 환경 vs 지금 환경

dbt가 맞는 곳 지금 환경

DB 종류	데이터 웨어하우스 (BigQuery, Snowflake 등)	MariaDB (OLTP 웹앱)
주요 작업	SELECT 기반 집계·변환 파이프라인	CRUD + 이력 관리
뷰 관리	dbt model로 관리	MariaDB VIEW (Django raw SQL)

대시보드용 VIEW 여러 개도, 이력 테이블 분석도, 계정 테이블도 전부 MariaDB + Django 안에서 돌아가는 OLTP 구조다. 여기에 dbt를 붙이면 같은 DB를 Django migrations와 dbt라는 두 개의 다른 워크플로우로 관리하게 되는 셈이라, 오히려 복잡도가 늘어난다. 규모가 커져도 이 적합도는 변하지 않는다 — 이건 규모의 문제가 아니라 애초에 워크로드 성격(OLTP vs 웨어하우스 변환)이 다른 아키텍처 문제이기 때문이다.

현실적인 권장 방향

• django-extensions의 graph_models도 완전한 답은 아니다. Django ORM 모델 기준으로만 그려서, managed=False로 되어 있는 테이블(이력 테이블 등)이 많으면 그런 것들은 누락된다.
• 지금 규모에서 가장 실용적인 방법은 마이그레이션을 작성할 때 스키마 문서(docs/db_spec.md 같은)를 같이 업데이트하는 규칙을 지키는 것이다. 컬럼 변경 마이그레이션을 작성할 때 ERD·명세서 업데이트를 체크리스트 항목으로 넣어두는 게, 오버엔지니어링 없이 가장 안정적인 방식이다.
• ERD 자동화 자체는 필요하다면 SchemaSpy를 기능 구현이 어느 정도 마무리된 시점에 한 번 돌리는 게 현실적이다. MariaDB에 직접 접속해서 managed=False 테이블, VIEW, 이력 테이블까지 전부 포함한 HTML ERD를 자동 생성해준다. jar 파일 + JDBC 드라이버만 있으면 별도 설치 없이 실행 가능하다.

결론

• dbt: 지금이든 나중이든 이 프로젝트에는 불필요 — 워크로드 성격 자체가 안 맞음
• 지금: 마이그레이션 작성 시 스키마 문서 수동 업데이트 유지
• 기능 완성 후: SchemaSpy로 전체 스키마 ERD를 한 번 뽑아서 문서화 마무리

---

이론적으로는 안 맞는다는 결론이 명확한데도, dbt는 여전히 한 번쯤 제대로 써보고 싶은 도구로 남아있다. 언젠가 데이터 웨어하우스 성격의 프로젝트를 만나면 그때 써보기로.