rss2.pub

한국어

English

한국어

English

Appearance

데이터베이스 마이그레이션 정책 ​

drizzle/에는 실행 가능한 순서대로 PostgreSQL SQL 마이그레이션이 들어 있습니다. src/web/migrate.ts는 이를 DATABASE_URL에 적용하고 종료합니다. 첫 공개 릴리스에는 0000부터 0008까지 포함되며, 빈 PostgreSQL 데이터베이스에 이 마이그레이션을 적용한 상태가 기준입니다. 공개 전 개인 DB의 업그레이드는 지원하지 않습니다.

마이그레이션 작성 ​

  • 먼저 src/infrastructure/persistence/schema.ts를 바꾸고 yarn drizzle-kit generate로 새 마이그레이션을 생성하세요. SQL, journal, snapshot을 함께 커밋하고, 병합 전에 생성된 SQL과 데이터에 미치는 영향을 검토하세요.
  • 태그가 붙은 릴리스에 포함된 마이그레이션은 수정·재정렬·삭제·번호 변경을 하지 마세요. 잘못된 부분은 후속 마이그레이션으로 고치세요. 운영 DB에 drizzle-kit push를 사용하지 마세요.
  • 짧은 업그레이드 동안 이전 버전과 새 버전이 공존할 수 있도록 추가형 변경을 우선하세요. 파괴적 변경은 필요하면 별도 릴리스로 나누고, 중단 시간과 데이터 재작성 절차를 명시하세요.
  • 스키마 변경은 새 DB 테스트를 통과해야 합니다. 두 번째 공개 릴리스부터는 바로 이전 안정 릴리스에서 만든 DB를 업그레이드하는 테스트도 실행하고, 액터 키· 팔로워·객체가 보존되는지 확인하세요. 보존할 수 없다면 호환되지 않는 릴리스로 취급하세요.
  • 마이그레이션 명령은 다시 실행해도 안전합니다. Drizzle이 적용 내역을 기록하고 아직 적용하지 않은 파일만 실행합니다. 기존 배포를 위해 서버 시작 시 자동 마이그레이션도 남겨 두지만, 운영자는 앱을 중지한 상태에서 명령을 명시적으로 실행해야 합니다. 마이그레이션 중 같은 DB에 새 인스턴스를 여러 개 시작하지 마세요. 실패했다면 원인을 조사한 뒤 다시 시도하세요.

포함된 코드 실행 ​

명령에는 DATABASE_URL만 필요하며, 같은 앱 버전에 포함된 SQL을 읽습니다. 첫 설치에서는 빈 DB에, 업그레이드에서는 백업을 마친 DB에 실행하세요.

sh
yarn db:migrate                         # source checkout; reads .env if present
node dist/web/migrate.js                # built app or container
rss2pub-migrate                         # Nix package

컨테이너에서는 기본 명령을 node dist/web/migrate.js로 바꾸고 앱과 같은 DATABASE_URL을 제공하세요. 명령이 실패하면 0이 아닌 상태로 종료하고 DB 연결을 닫습니다. E2E 테스트는 빈 PostgreSQL DB에서 실제 명령을 실행하고 재실행해 멱등성을 확인합니다.

운영 환경 업그레이드 ​

  1. 대상 릴리스의 변경 기록과 마이그레이션 안내를 읽으세요. 대상 이미지 버전을 고정하고 이전 이미지도 보관하세요.

  2. 앱을 중지하고 Fedify 큐/KV 상태, 액터 키, 팔로워, 객체를 포함한 일관된 PostgreSQL 백업을 만드세요. 액터 개인 키가 DB에 저장되므로 백업은 비밀로 취급해야 합니다. 예를 들면 다음과 같습니다.

    sh
    pg_dump --format=custom --file=rss2pub-before-upgrade.dump "$DATABASE_URL"

  3. 앱이 중지된 상태에서 새 버전의 마이그레이션 명령을 실행하세요. 실패하면 앱을 중지한 채 원인을 조사하세요. 성공했다면 새 버전 인스턴스 하나를 시작하고 /readyz를 기다린 뒤, 로그를 확인하고 원래 인스턴스 수로 늘리세요.

  4. 갱신된 인스턴스에서 액터·객체 URL, 피드 폴링, 원격 팔로우를 확인하세요. 검증이 끝날 때까지 백업을 보관하세요.

자동 다운 마이그레이션은 없습니다. 스키마 변경 후 업그레이드가 실패했다면 새 앱을 중지하고, 이전 버전을 다시 시작하기 전에 백업을 별도의 깨끗한 DB로 복구하세요. 운영에서 복구에 의존하기 전에 복구 절차를 시험하세요. 새 스키마에 이전 버전 실행 파일을 연결하지 마세요.

ORIGIN은 ActivityPub 신원의 일부입니다. 이를 바꾸거나 운영 중인 DB를 같은 주소의 빈 DB로 교체하면 저장된 액터 키와 팔로워 관계가 사라집니다. 이는 일반적인 스키마 마이그레이션이 아닙니다.