사용 가능 플랜: Entry, Professional, Enterprise, Enterprise Advanced

데이터베이스 마이그레이션은 어려운 작업일 수 있으며, 이전에 마이그레이션을 수행한 적이 없다면 일부 필수 단계를 간과하거나 잘못 해석하기 쉽습니다. migration-assist 도구는 에어갭 배포 환경에서도 실행해야 할 작업을 자동화하여 효율적이고 오류 없는 마이그레이션 경험을 제공합니다.

이 도구가 Mattermost 배포 환경에 적합한지 확실하지 않으십니까? Mattermost 배포 환경을 기반으로 맞춤형 안내를 원하는 Mattermost 고객은 Mattermost 전문가에게 문의하세요.

설치#

GitHub 리포지터리 릴리즈 페이지에서 Mattermost migration-assist 도구를 다운로드하세요.

migration-assist 도구를 Mattermost 배포 환경과 동일한 서버에서 실행할 수 있지만, 대신 Mattermost 서버와 동일한 네트워크의 가상 머신에서 실행하는 것을 권장합니다. 도구 자체는 경량이며 큰 서버가 필요하지 않습니다. CPU 코어 2개와 RAM 16GB의 서버면 충분합니다. 원하는 경우 migration-assist 도구를 직접 다운로드하여 컴파일할 수도 있습니다.

MySQL에서 PostgreSQL로 데이터를 마이그레이션하려면 pgloader 도구도 설치해야 합니다. Mattermost 서버와 동일한 네트워크의 가상 머신에서 pgloader용 공식 Mattermost Docker 이미지(mattermost/mattermost-pgloader:latest)를 사용하여 pgloader를 실행하는 것을 권장합니다. mattermost-pgloader-docker 리포지터리에서 이미지를 직접 빌드할 수도 있습니다. 인증 오류가 발생하면 MySQL에 대한 지원되지 않는 인증을 참조하세요. 자세한 내용은 pgloader 설치 문서를 참조하세요.

사용법#

1단계 - MySQL 데이터베이스 스키마 확인#

다음 명령을 실행하여 MySQL 데이터베이스 스키마를 확인하세요:

migration-assist mysql ""  # 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 "" \
  --run-migrations \
  --mattermost-version=""

• 예시: postgres://user:password@address:5432/db_name
• 예시: 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="" \
  --postgres="" \
  --remove-null-chars \
  > migration.load

• 기본적으로 텍스트 칼럼의 null 문자는 제거됩니다. --remove-null-chars=false로 비활성화하세요.

• 힙 소진이 발생하면 migration.load를 편집하고 WITH 블록 아래에 다음을 설정하세요:

  prefetch rows = 1000
  

4단계 - pgloader 실행#

생성된 구성 파일로 pgloader를 실행하세요:

pgloader migration.load > migration.log

migration.log에서 오류(예: 중복 키 또는 테이블 누락 경고)를 주의 깊게 검토하세요. 빌드/인증 문제를 방지하려면 mattermost/mattermost-pgloader:latest Docker 이미지를 사용하세요.

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

실행하세요:

migration-assist postgres post-migrate --create-indexes ""

• --create-indexes 플래그는 Posts 및 FileInfo의 전문 검색 인덱스와 다른 모든 Mattermost 인덱스를 재빌드합니다.
• 해당 플래그를 생략하면 Posts 및 FileInfo에 대한 전문 검색 인덱스만 복원합니다.

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

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

Playbooks, Boards, Calls에 대한 pgloader 구성을 생성하세요:

migration-assist pgloader boards \
  --mysql="" \
  --postgres="" > boards.load
migration-assist pgloader playbooks \
  --mysql="" \
  --postgres="" > playbooks.load
migration-assist pgloader calls \
  --mysql="" \
  --postgres="" > 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 도구는 3가지 핵심 명령어를 제공합니다:

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로 마이그레이션 중 오류 문제 해결을 참조하세요.