PostgreSQL 마이그레이션 자동화

데이터베이스 마이그레이션은 부담스러운 작업이며, 마이그레이션을 해 본 적이 없다면 필요한 단계 중 일부를 놓치거나 잘못 이해하기 쉽습니다. Mattermost의 migration-assist 도구는 수행해야 할 작업을 자동화해 에어갭 배포 환경에서도 효율적이고 오류 없는 마이그레이션 경험을 제공합니다.

이 도구가 자사 Mattermost 배포에 적합한지 확신이 서지 않나요? 배포 환경에 맞춘 안내가 필요한 Mattermost 고객은 Mattermost 전문가에게 문의할 수 있습니다.

설치

GitHub 저장소의 릴리스 페이지에서 Mattermost migration-assist 도구를 다운로드하세요.

migration-assist 도구를 Mattermost 배포와 동일한 서버에서 실행할 수도 있지만, Mattermost 서버와 같은 네트워크에 있는 가상 머신에서 실행할 것을 권장합니다. 도구 자체는 가볍기 때문에 큰 서버가 필요하지 않습니다. CPU 코어 2개와 RAM 16GB를 갖춘 서버면 충분합니다. 원한다면 migration-assist 도구를 직접 내려받아 컴파일할 수도 있습니다.

또한 MySQL에서 PostgreSQL로 데이터를 마이그레이션하려면 pgloader 도구를 설치해야 합니다. pgloader는 Mattermost 서버와 같은 네트워크에 있는 가상 머신에서 실행할 것을 권장합니다. Mattermost가 제공하는 공식 pgloader Docker 이미지(mattermost/pgloader:latest)를 사용할 수 있습니다. 다만 이 이미지는 현재 MySQL의 caching_sha2_password 인증 플러그인을 지원하지 않는다는 점에 유의하세요. caching_sha2_password 지원이 필요하다면 qitab/qmynd 라이브러리를 포함해 직접 이미지를 빌드해야 합니다. 자세한 내용은 pgloader 설치 문서를 참고하세요.

사용법

1단계 - MySQL 데이터베이스 스키마 점검

다음 명령을 실행해 MySQL 데이터베이스 스키마를 점검합니다.

migration-assist mysql "<MYSQL_DSN>"  # example DSN: "user:password@tcp(address:3306)/db_name"

이 명령은 준비 상태를 출력하고 일반적인 문제에 필요한 수정 사항을 알려 줍니다. 수정용 플래그는 다음과 같습니다(모두 함께 사용할 수 있습니다).

--fix-artifacts   Removes the artifacts from older versions of Mattermost
--fix-unicode     Strips unsupported Unicode characters from MySQL tables
--fix-varchar     Removes rows exceeding column lengths

2단계 - PostgreSQL 데이터베이스 스키마 생성

마이그레이션을 실행하기 전에 public 스키마의 소유자가 마이그레이션 사용자인지 확인하세요.

sudo -u postgres psql -d mattermost -c "ALTER SCHEMA public OWNER TO mmuser; GRANT ALL ON SCHEMA public TO mmuser;"

그런 다음 실행합니다.

migration-assist postgres "<POSTGRES_DSN>" \
  --run-migrations \
  --mattermost-version="<MATTERMOST_VERSION>"

• <POSTGRES_DSN> 예시: postgres://user:password@address:5432/db_name
• <MATTERMOST_VERSION> 예시: 10.5.4

기본적으로 마이그레이션 전에 두 가지 사전 점검이 실행됩니다.

• --check-schema-owner=true
• --check-tables-empty=true

비활성화하려면 다음과 같이 지정합니다.

--check-schema-owner=false \
--check-tables-empty=false

3단계 - pgloader 구성 생성

다음 명령을 실행해 pgloader 구성 파일을 생성합니다.

migration-assist pgloader \
  --mysql="<MYSQL_DSN>" \
  --postgres="<POSTGRES_DSN>" \
  --remove-null-chars \
  > migration.load

• 기본적으로 텍스트 컬럼의 널 문자는 제거됩니다. --remove-null-chars=false로 비활성화할 수 있습니다.

• 힙이 부족해지면 migration.load를 편집해 WITH 블록 아래에 다음을 설정하세요.

  prefetch rows = 1000

4단계 - pgloader 실행

생성한 구성 파일로 pgloader를 실행합니다.

pgloader migration.load > migration.log

migration.log에 오류(예: 중복 키 또는 테이블 누락 경고)가 있는지 꼼꼼히 확인하세요. 빌드·인증 문제를 피하려면 mattermost/pgloader:latest Docker 이미지를 사용하세요.

5단계 - 전문 검색 인덱스 복원 및 전체 인덱스 생성

다음을 실행합니다.

migration-assist postgres post-migrate --create-indexes "<POSTGRES_DSN>"

• --create-indexes 플래그는 Posts와 FileInfo의 전문 검색 인덱스를 포함해 나머지 모든 Mattermost 인덱스를 다시 생성합니다.
• 이 플래그를 생략하면 Posts와 FileInfo의 전문 검색 인덱스만 복원합니다.

자세한 내용은 전문 검색 인덱스 복원 문서를 참고하세요.

6단계 - 플러그인 마이그레이션 완료

Playbooks, Boards, Calls용 pgloader 구성을 생성합니다.

migration-assist pgloader boards \
  --mysql="<MYSQL_DSN>" \
  --postgres="<POSTGRES_DSN>" > boards.load
migration-assist pgloader playbooks \
  --mysql="<MYSQL_DSN>" \
  --postgres="<POSTGRES_DSN>" > playbooks.load
migration-assist pgloader calls \
  --mysql="<MYSQL_DSN>" \
  --postgres="<POSTGRES_DSN>" > calls.load

각각 실행합니다.

pgloader boards.load           > boards_migration.log
pgloader playbooks.load        > playbooks_migration.log
pgloader calls.load            > calls_migration.log

사용하지 않는 플러그인은 건너뛰고, 로그에서 JSON 오류나 테이블 누락 오류가 있는지 확인하세요. 자세한 내용은 플러그인 마이그레이션 가이드를 참고하세요.

7단계 - PostgreSQL을 사용하도록 Mattermost 구성

config.json이나 환경 변수에서 다음을 수정합니다.

"SqlSettings": {
  "DriverName": "postgres",
  "DataSource": "postgres://mmuser:pass@db:5432/mattermost?sslmode=disable"
}

구성이 데이터베이스에 저장되어 있었다면 MM_CONFIG도 그에 맞게 수정하세요. 자세한 내용은 환경 구성 설정 문서를 참고하세요.

에어갭 환경

에어갭 환경에서 마이그레이션하려면 다음 단계를 따르세요.

1. 확인: 개선 사항과 수정 사항을 적용받을 수 있도록 migration-assist 바이너리가 최신 버전인지 확인합니다.
2. 전송: 최신 migration-assist 바이너리를 에어갭 환경으로 전송합니다(예: 보안 매체 사용).

3. 생성: 수정 플래그를 사용해 MySQL 스키마와 데이터 출력을 생성합니다. 이 명령은 mysql.output을 만듭니다.

   migration-assist mysql "user:pass@tcp(localhost:3306)/mattermost" \
     --fix-artifacts --fix-unicode --fix-varchar > mysql.output

4. 적용: 생성된 출력을 사용해 마이그레이션을 적용합니다.

   migration-assist postgres \
     "postgres://mmuser:pass@localhost:5432/imported?sslmode=disable" \
     --run-migrations --applied-migrations="./mysql.output"

5. 계속: 위의 3단계부터 7단계까지 이어서 진행해 데이터 전송과 구성을 완료합니다.

도구 명령

migration-assist 도구는 세 가지 핵심 명령을 제공합니다.

1. migration-assist mysql — MySQL 스키마 준비 상태를 점검하고 수정 방법을 제안합니다.
2. migration-assist postgres — PostgreSQL 스키마를 생성하고 마이그레이션을 적용합니다.
3. migration-assist pgloader — 데이터 전송용 pgloader 구성을 생성합니다.

migration-assist 도구 컴파일

Go v1.22 이상이 필요합니다. 다음 명령으로 설치합니다.

go install github.com/mattermost/migration-assist/cmd/migration-assist@latest

문제 해결

MySQL에서 PostgreSQL로 마이그레이션하는 중 발생하는 오류 해결을 참고하세요.