원문 캡처 · github.com
원문 캡처 · github.com

pgdeclare는 PostgreSQL 스키마를 현재 상태를 설명하는 SQL 파일로 관리하고, 실제 데이터베이스와의 차이를 계산해 적용하는 도구다. 데이터베이스 변경 이력 대신 선언된 스키마를 기준으로 작업하며, 자동으로 판단하기 어려운 변경에는 별도의 마이그레이션 블록을 쓴다.

각 테이블을 CREATE TABLE 문으로 정의하면 pgdeclare가 임시 데이터베이스에서 SQL을 실행해 원하는 스키마를 만들고, pg_catalog를 통해 실제 스키마와 비교한다. 변경 사항은 diff로 확인하거나 apply로 적용할 수 있다. 이름 변경이나 데이터 채우기처럼 차이만으로 추론할 수 없는 작업은 DDL 옆에 @migrate-before 또는 @migrate-after 블록으로 작성한다. 이 블록은 데이터베이스별로 한 번 실행되고 해시 기록에 남는다. 실행 후 블록을 수정하면 변경을 조용히 무시하지 않고 실행을 거부한다. 데이터가 있는 테이블의 파괴적 변경에는 @drop 지시자가 필요하다.

설치는 Python 3.12 이상과 PostgreSQL 14~18 서버가 필요하다. 대상 데이터베이스의 스키마를 소유한 역할로 연결해야 하며, 기본 설정에서는 실행 때마다 같은 서버에 임시 데이터베이스를 만들고 삭제하므로 역할에 CREATEDB 권한도 필요하다. 이 권한이 없으면 직접 만든 계획 데이터베이스를 --plan-database 옵션으로 지정할 수 있다.

bash
pip install pgdeclare
# or, inside a uv project
uv add pgdeclare
bash
export DATABASE_URL=postgresql://app:secret@localhost:5432/app

pgdeclare diff # what would change, as a summary plus SQL
pgdeclare diff --json # the same, machine-readable
pgdeclare diff --exit-code # exit 2 when anything is pending (for CI)
pgdeclare apply --dry-run # plan only, nothing written
pgdeclare apply --dry-run --prove # rehearse the real run on a throwaway clone
pgdeclare apply # converge the database

제작자에 따르면 pgdeclare는 버전 0.1.1이며, Powertime의 운영 스키마를 2025년 12월 10일 서비스에 투입한 뒤 관리하고 있다. 버전 1.0 전까지는 하위 호환성이 보장되지 않을 수 있다. 자세한 적용 범위와 안전 관련 조건은 안전 문서에서 확인할 수 있다.

프로젝트: pgdeclare 저장소. 제작 배경은 데이터베이스 스키마는 읽을 수 있는 코드여야 한다에서 설명한다. 사용법은 명령줄 문서, Python API 문서, 스키마 파일 문서, 지원 범위 문서, 설정 문서에서 볼 수 있다.