Dbmate

다중 데이터베이스 지원 및 범용 SQL 마이그레이션

Dbmate는 MySQL, MariaDB, PostgreSQL, SQLite, ClickHouse를 지원하며, BigQuery와 Spanner(현재 PostgreSQL Dialect 한정)도 연결할 수 있습니다. 스키마 변경은 평이한 SQL로 작성하며, 마이그레이션 파일은 타임스탬프 버전 형식(예: 20151127184807_create_users_table.sql)을 사용해 여러 개발자 간 버전 번호 충돌을 방지합니다.

트랜잭션 기반 실행 및 자동 DB 생성·삭제

각 마이그레이션은 데이터베이스가 지원하는 경우 단일 트랜잭션 안에서 원자적으로 실행됩니다. 개발 및 테스트 환경에서 유용한 데이터베이스 생성과 삭제 기능을 함께 제공합니다.

스키마 파일 저장 및 환경변수 기반 설정

마이그레이션 적용 후 ./db/schema.sql 파일을 자동 갱신하므로 git에서 스키마 변경 사항을 손쉽게 비교할 수 있습니다. 데이터베이스 연결 URL은 기본적으로 DATABASE_URL 환경변수 또는 –url 옵션으로 지정하며, 현재 디렉터리의 .env 파일에서 환경변수를 자동으로 불러오는 기능을 내장하고 있습니다.

데이터베이스 준비 대기 및 단일 바이너리 배포

Docker 개발 환경 등에서 DB 서버가 즉시 준비되지 않는 상황을 위해 `dbmate wait` 명령과 –wait 옵션이 제공됩니다. 1초 간격으로 최대 60초(사용자 지정 가능)까지 연결을 시도합니다. 도구 자체는 외부 의존성 없는 단일 자체 완결형 바이너리로 배포됩니다.

설치 방법

Windows에서는 다음 winget 명령을 사용해 설치할 수 있습니다.

• winget install –id amacneil.dbmate –exact

설치 후 다음 명령으로 도움말을 확인합니다.

• dbmate –help

기본 명령

• dbmate new — 새 마이그레이션 파일 생성
• dbmate up — 데이터베이스 생성(필요 시) 후 대기 중인 마이그레이션 적용
• dbmate migrate — 대기 중인 마이그레이션만 적용
• dbmate create / drop — 데이터베이스 생성 및 삭제
• dbmate rollback — 가장 최근 마이그레이션 롤백
• dbmate status — 전체 마이그레이션 상태 표시
• dbmate dump — 현재 스키마를 schema.sql 파일로 덤프
• dbmate load — schema.sql 파일을 데이터베이스로 적재
• dbmate wait — 데이터베이스 서버가 준비될 때까지 대기

데이터베이스 연결

DATABASE_URL은 `protocol://username:password@host:port/database_name?options` 형식으로 지정하며, 사용 가능한 프로토콜은 mysql, postgres, postgresql, sqlite, sqlite3, clickhouse입니다. PostgreSQL은 기본적으로 TLS 연결을 요구하므로 비암호화 연결이 필요한 경우 sslmode=disable을 추가합니다. SQLite는 호스트 없이 파일 경로로 지정합니다(예: `sqlite:db/database.sqlite3`). ClickHouse는 clickhouse://(네이티브 TCP, 기본 포트 9000), clickhouse+http://(기본 포트 8123), clickhouse+https://(기본 포트 8443) 스킴을 지원합니다.

마이그레이션 작성과 적용

`dbmate new create_users_table` 명령으로 새 마이그레이션 파일을 생성한 뒤, — migrate:up 블록에 CREATE TABLE 등 평이한 SQL을 기술합니다. `dbmate up`을 실행하면 데이터베이스가 없으면 생성하고, 대기 중인 마이그레이션을 차례로 적용한 뒤 schema.sql 파일을 갱신합니다. 롤백이 필요한 경우 — migrate:down 블록을 작성한 뒤 `dbmate rollback`을 실행합니다.

테스트 환경에서 DB 재생성

개발용과 테스트용 연결 문자열을 각각 DATABASE_URL과 TEST_DATABASE_URL 환경변수에 저장해 두고, 테스트 스크립트에서 `dbmate -e TEST_DATABASE_URL drop` 후 `dbmate -e TEST_DATABASE_URL –no-dump-schema up`을 실행하여 테스트 데이터베이스를 빠르게 재생성할 수 있습니다.

Docker 환경에서의 사용

GitHub Container Registry의 ghcr.io/amacneil/dbmate 이미지를 `–network=host` 옵션과 함께 사용하며, 로컬 디렉터리를 컨테이너 내부에 바인드 마운트하여 마이그레이션 파일을 공유합니다.

지원 환경·요구사항

Windows에 winget으로 설치 가능한 단일 바이너리(x64)입니다. PostgreSQL 연결은 기본적으로 TLS가 요구되며, ClickHouse 클러스터 연동을 위해서는 별도의 쿼리 매개변수가 필요합니다. 스키마 덤프 기능은 PATH에 pg_dump, mysqldump, sqlite3가 존재할 때 동작합니다.

제한·라이선스·확인사항

Dbmate의 소스 코스는 MIT 라이선스로 배포됩니다. Spanner 지원은 PostgreSQL Dialect으로 생성된 데이터베이스에 한정되며, 스키마 덤프는 현재 지원되지 않습니다. 마이그레이션 기본 순서는 숫자 순이지만, 기본적으로 적용 순서가 어긋난 마이그레이션을 차단하지는 않으므로 strict 동작이 필요한 경우 –strict 옵션을 사용합니다.

버전·업데이트

v2.35.0 업데이트에서는 README 및 소스 코멘트의 오타 수정, BigQuery InsertMigration의 추가 바인딩 인자 제거, GitHub Actions의 setup-go/setup-node 의존성 버전 갱신, google.golang.org/grpc 1.80.0 → 1.82.1 업그레이드가 포함되었습니다.