자동화된 PostgreSQL 마이그레이션#

plans-img 모든 플랜 에서 사용 가능

deployment-img self-hosted 배포

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

이 도구가 귀하의 Mattermost 배포에 적합한지 확실하지 않으신가요? Mattermost 배포에 기반한 맞춤형 가이드가 필요한 Mattermost 고객은 Mattermost Expert 에 문의하실 수 있습니다.

설치#

GitHub 저장소의 releases page 에서 Mattermost migration-assist 도구를 다운로드하세요.

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

MySQL에서 PostgreSQL로 데이터를 마이그레이션하려면 pgloader 도구도 설치해야 합니다. pgloader 를 Mattermost 서버와 동일한 네트워크의 가상 머신에서 실행하는 것을 권장합니다. 자세한 내용은 pgloader 설치 문서를 참조하세요.

사용법#

중요

마이그레이션을 수행하기 위한 필요한 환경이 갖춰져 있는지 확인하세요. MySQL과 PostgreSQL 데이터베이스가 실행 중이고 접근 가능한지 확인하세요. PostgreSQL 인스턴스 설정에 대한 자세한 내용은 Mattermost 데이터베이스 준비 문서를 참조하세요.

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                 Removes the unsupported unicode characters from MySQL tables
--fix-varchar                 Removes the rows with varchar overflow

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

Postgres 데이터베이스 스키마를 생성하려면 다음 명령어를 실행하세요:

migration-assist postgres "<POSTGRES_DSN>" --run-migrations --mattermost-version="<MATTERMOST_VERSION>" # example DSN: "postgres://user:password@address:5432/db_name", example Mattermost version: "v9.4.0"

이 명령어는 필요한 마이그레이션을 다운로드하고 Postgres 데이터베이스에 적용합니다. 마이그레이션하는 Mattermost 버전을 지정하기 위해 --mattermost-version 플래그가 필요합니다.

마이그레이션을 실행하기 전에 몇 가지 검사를 실행하기 위해 migration-assist postgres 명령어와 함께 사용할 수 있는 두 가지 플래그가 있습니다. 다음 플래그를 false로 설정하여 비활성화할 수 있습니다:

--check-schema-owner          Check if the schema owner is the same as the user running the migration (default true)
--check-tables-empty          Check if tables are empty before running migrations (default true)

3단계 - pgloader 구성 생성#

pgloader 구성을 생성하려면 다음 명령어를 실행하세요:

migration-assist pgloader --mysql="<MYSQL_DSN>" --postgres="<POSTGRES_DSN>" > migration.load

이 명령어는 MySQL에서 Postgres로 데이터를 마이그레이션하는 데 사용할 수 있는 pgloader 구성 파일을 생성합니다.

생성된 구성에는 텍스트 유형 데이터에서 null 문자를 제거하는 설정이 있습니다. 이는 Postgres에 데이터를 삽입하는 동안 마이그레이션이 오류를 반환하지 않도록 하기 위한 것입니다. 그러나 이 동작을 비활성화하려면 --remove-null-chars 를 false 로 설정할 수 있습니다.

4단계 - pgloader 실행#

생성된 구성 파일로 pgloader 실행:

pgloader migration.load > migration.log

마이그레이션 과정에서 오류가 발생했는지 분석하기 위해 로그 파일을 주의 깊게 읽으세요. 오류가 발생한 경우 Mattermost에 추가 지침을 요청하세요.

5단계 - 전체 텍스트 인덱스 복원#

Posts 및 FileInfo 테이블의 전체 텍스트 인덱스를 생성하려면 다음 명령어를 실행하세요:

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

이 명령어는 Posts 및 FileInfo 테이블의 전체 텍스트 인덱스를 생성합니다. 자세한 내용은 전체 텍스트 인덱스 복원 문서를 참조하세요.

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

협업 플레이북, 보드 및 통화를 위한 마이그레이션 구성을 생성하세요:

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를 실행하세요:

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

마이그레이션 과정에서 오류가 발생했는지 분석하기 위해 로그 파일을 주의 깊게 읽으세요. Playbooks, Boards 및 Calls 마이그레이션에 대한 정보는 플러그인 마이그레이션 문서를 참조하세요.

7단계 - 새로운 PostgreSQL 데이터베이스를 사용하도록 Mattermost 구성#

이것은 마이그레이션 프로세스의 마지막 단계로, 새로운 PostgreSQL 데이터베이스를 가리키도록 Mattermost 구성을 업데이트해야 합니다. 이를 위해 config.json 에서 SqlSettings.DataSource 와 SqlSettings.DriverName 필드를 찾아 새로운 PostgreSQL 데이터베이스 연결 세부 정보를 반영하도록 이러한 필드를 수정하세요. 자세한 내용은 환경 구성 설정 문서를 참조하세요.

참고

구성이 데이터베이스에 저장된 경우 마이그레이션 세부 정보는 데이터베이스의 구성 문서를 참조하세요. 마이그레이션이 완료되면 MM_CONFIG 환경 변수도 새로운 DSN을 가리키도록 업데이트해야 합니다.

에어갭 환경#

migration-assist 도구는 마이그레이션에 필요한 모든 파일을 포함하고 있어 저장소에 대한 외부 액세스가 필요하지 않습니다. 에어갭을 통해 전송되면 도구는 독립적으로 작동합니다. 외부 의존성 없이 에어갭 환경에서 MySQL에서 PostgreSQL로 원활한 마이그레이션을 수행하려면 아래 지침을 따르세요:

  1. 개선 사항과 수정 사항의 이점을 얻기 위해 migration-assist 바이너리가 최신 버전인지 확인하세요.

  2. 에어갭 환경으로 migration-assist 바이너리의 최신 버전을 전송하세요.

  3. Unicode, 아티팩트 및 VARCHAR에 대한 --fix 플래그를 사용하여 MySQL에서 스키마와 데이터 출력 파일을 생성하세요. 이 단계는 MySQL 데이터베이스가 마이그레이션 준비가 되었는지 확인하는 중요한 단계입니다. 다음 명령어는 MySQL 데이터베이스 스키마를 확인하고, 필요한 수정 사항을 적용하며, 자동으로 mysql.output 이라는 파일을 생성합니다:

    migration-assist mysql "user:password@tcp(localhost:3306)/mattermost" --fix-unicode --fix-artifacts --fix-varchar

  4. mysql.output 파일을 사용하여 스키마와 데이터를 PostgreSQL 데이터베이스에 적용하세요:

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

  5. migration-assist 도구를 사용하여 마이그레이션 프로세스를 완료하려면 위의 step 3 부터 step 7 까지 따르세요.

도구 명령어#

migration-assist 도구는 3가지 핵심 유틸리티 명령어를 제공합니다:

  1. migration-assist mysql

    MySQL 데이터베이스 스키마를 확인하여 마이그레이션 준비 상태를 확인하고, 일반적인 문제에 대한 수정 사항을 제공합니다. migration-assist 도구 설치에 대한 자세한 내용은 아래의 install 섹션을 참조하세요.

  2. migration-assist postgres

    PostgreSQL 데이터베이스 스키마를 생성하고, 필요한 마이그레이션을 다운로드하여 적용함으로써 Mattermost 배포를 준비합니다.

  3. migration-assist pgloader

    DSN 값에서 pgloader 구성을 생성하여 정확한 데이터 전송을 보장합니다. pgloader 도구 설치에 대한 자세한 내용은 install pgloader 문서를 참조하세요.

migration-assist 도구 컴파일하기#

Go 툴체인을 사용하여 migration-assist 도구를 다운로드하고 컴파일할 수 있습니다. 이 도구는 Go 컴파일러 v1.22 이상이 필요합니다.

도구를 설치하려면 go install 을 사용하세요:

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

문제 해결#

MySQL에서 PostgreSQL로 마이그레이션 중 발생하는 오류 해결 방법은 troubleshooting errors during migration from MySQL to PostgreSQL 를 참조하세요