DocumentLibrary 이중 데이터베이스 배포 가이드

목적

DocumentLibrary는 PostgreSQL 및 MySQL/MariaDB를 모두 지원한다. 애플리케이션은 DATABASE_URL의 프로토콜에서 방언을 추론하며, DATABASE_DIALECT를 함께 설정한 경우 두 값이 일치하는지 시작 전에 검증한다. 이 검증은 PostgreSQL URL에 MySQL 드라이버를 적용하거나 그 반대의 구성이 조용히 배포되는 문제를 차단한다.

선택 항목	PostgreSQL	MySQL/MariaDB
DATABASE_DIALECT	postgresql	mysql
URL 형식	postgresql://USER:PASSWORD@HOST:5432/DATABASE	mysql://USER:PASSWORD@HOST:3306/DATABASE
마이그레이션 폴더	drizzle/postgres-migrations	drizzle/legacy/mysql/migrations
런타임 드라이버	pg	mysql2
기본 포트	5432	3306

DATABASE_DIALECT는 URL에서 추론할 수 있으나, 운영 배포에서는 의도를 명시하고 URL과의 불일치를 조기에 실패시키기 위해 설정하는 것을 권장한다.

배포 흐름

배포의 시작 명령은 pnpm start:with-migrations이다. 이 명령은 먼저 pnpm db:migrate를 수행하고, 성공한 경우에만 애플리케이션 서버를 시작한다. 마이그레이션에는 Drizzle의 방언별 메타데이터 테이블이 사용되므로 이미 적용된 파일은 다시 실행되지 않는다.

단계	실행 내용	실패 시 결과
1	DATABASE_URL과 DATABASE_DIALECT의 방언 일치 검사	서버를 시작하지 않음
2	해당 방언의 Drizzle 마이그레이션 실행	서버를 시작하지 않음
3	node ./dist/index.js로 애플리케이션 기동	readiness endpoint 제공
4	/api/directory/readiness 상태 확인	배포 플랫폼의 health check가 실패를 감지

배포 플랫폼 구성은 PostgreSQL 배포를 기본값으로 명시한다. MySQL/MariaDB 배포를 만들 경우 서비스 환경 변수에서 DATABASE_DIALECT=mysql로 바꾸고 MySQL URL을 제공해야 한다. 기존 PostgreSQL 마이그레이션 폴더와 MySQL 마이그레이션 폴더를 혼용해서는 안 된다.

최초 설치 화면

/setup 화면에서는 PostgreSQL 또는 MySQL/MariaDB를 선택한다. 선택값은 설치 검증 및 설치 API에 전달되고, 서버는 URL 프로토콜과 선택한 방언이 일치하는지 확인한다. 설치 API는 선택된 마이그레이션 체인을 적용한 후 단독 관리자 또는 DirectoryService 설정을 저장한다.

개발 서버 재초기화

개발 서버는 데이터 보존이 필요하지 않은 경우 다음 순서로 복구한다.

1. 서비스의 DATABASE_URL이 가리키는 개발용 데이터베이스를 삭제하고 같은 이름의 빈 데이터베이스를 만든다.
2. DATABASE_DIALECT가 URL 프로토콜과 일치하는지 확인한다.
3. 최신 커밋을 배포한다. 시작 명령이 해당 방언의 전체 마이그레이션을 적용한다.
4. /api/directory/readiness가 ready: true를 반환하는지 확인한다.

운영 데이터베이스는 삭제하거나 개발용 절차로 재초기화하면 안 된다. 운영 환경의 스키마 변경은 백업, 검토, 롤백 계획을 포함한 별도 변경 절차를 사용한다.

점검 명령

pnpm run check
pnpm run build
DATABASE_URL='postgresql://...' DATABASE_DIALECT=postgresql pnpm run db:migrate
DATABASE_URL='mysql://...' DATABASE_DIALECT=mysql pnpm run db:migrate

마이그레이션 명령은 반복 실행해도 안전해야 한다. 각 방언에서 빈 데이터베이스에 한 번 적용한 뒤 다시 실행하여, 추가 DDL 없이 성공하는지 확인한다.