MySQL에서 PostgreSQL로 마이그레이션

Mattermost v8.0부터 PostgreSQL이 플랫폼의 성능과 기능을 강화하기 위한 Mattermost의 기본 데이터베이스입니다. MySQL 데이터베이스에서 마이그레이션하려는 커뮤니티 구성원을 지원하는 일이 중요하다는 점을 인식하고, Mattermost는 관련 지침과 모범 사례를 미리 마련했습니다.

• PostgreSQL 마이그레이션 자동화 - 마이그레이션 과정을 간소화하고 발생할 수 있는 어려움을 줄이며 매끄러운 전환을 돕는 종합 지침과 migration-assist 도구입니다.
• PostgreSQL 수동 마이그레이션 - 조직에 마이그레이션 과정을 담당할 데이터베이스 관리자가 있거나, migration-assist 도구가 무엇을 자동화하는지 파악하고 싶을 때 좋은 선택입니다.

자주 묻는 질문

Mattermost는 왜 MySQL 지원을 중단하나요?

Mattermost는 개발을 간소화하고 더 효율적이고 최적화된 기능 제공에 집중하기 위해 MySQL 데이터베이스 지원을 중단하기로 결정했습니다. 일반적으로 더 발전되어 있고 엔터프라이즈 환경에 더 적합하다고 평가받는 PostgreSQL만 지원함으로써, Mattermost는 복잡도를 낮추고 성능을 개선하며 제품 개선에 자원을 더 효과적으로 배분할 수 있습니다. 이 변경은 모든 Mattermost 배포에서 데이터베이스 상호작용이 더 일관되고 견고하며 확장 가능하도록 보장합니다.

Mattermost를 업그레이드하기 전에 PostgreSQL로 마이그레이션하는 것이 권장되나요?

그렇습니다. 또한 PostgreSQL로 마이그레이션하기 전에 Mattermost 서버를 v8.x 이상으로 업그레이드할 것을 권장합니다.

migration-assist를 Mattermost 서버에서 실행할 수 있나요?

기술적으로는 가능합니다. migration-assist 도구는 Mattermost 서버에서 실행할 수 있습니다. 다만 성능 문제를 피하려면 별도의 서버에서 실행하는 것을 권장합니다. 마이그레이션 과정이 운영 환경에 영향을 주지 않도록 MySQL 데이터베이스의 사본을 대상으로 마이그레이션을 수행할 것을 권장합니다.

PostgreSQL 서버는 얼마나 커야 하나요?

PostgreSQL 서버의 규모는 처음에는 MySQL 서버와 동일하게 맞춰야 합니다. 이후 PostgreSQL 서버의 성능을 모니터링하면서 필요에 따라 리소스를 조정할 것을 권장합니다.

migration-assist를 실행하는 서버는 얼마나 커야 하나요?

도구 자체는 가볍기 때문에 큰 서버가 필요하지 않습니다. 기본 구성에서는 CPU 코어 2개와 RAM 16GB를 갖춘 서버면 충분합니다. 다만 MySQL 데이터베이스의 크기, 허용 가능한 다운타임, pgloader 구성에 따라 리소스를 조정해야 할 수 있습니다.

Mattermost가 pgloader를 함께 제공하나요, 아니면 별도로 설치해야 하나요?

Mattermost는 Mattermost 서버에 pgloader를 함께 제공하지 않습니다. pgloader는 별도로 설치해야 합니다. 자세한 내용은 pgloader 설치 문서를 참고하세요.

Boards, Playbooks, Calls 외에 다른 플러그인용 마이그레이션도 있나요?

NPS-plugin 등 다른 플러그인용 마이그레이션도 개발 중입니다. 업데이트를 기다려 주세요.

이 절차가 AWS RDS 데이터베이스를 지원하나요?

네, 이 절차는 AWS RDS 데이터베이스를 지원합니다. 다만 마이그레이션 과정에서 데이터베이스에 접근할 수 있도록 보안 그룹 설정을 조정해야 할 수 있습니다.

Mattermost는 MariaDB를 지원하나요? 지원하지 않는다면 이유는 무엇인가요?

Mattermost는 MariaDB를 지원하지 않습니다. 가장 큰 이유는 단일 데이터베이스 기술에 집중해 개발과 유지 관리를 간소화하기 위해서입니다. PostgreSQL로 표준화함으로써 Mattermost는 최적화된 기능, 향상된 성능, 더 집중된 엔지니어링 역량을 제공할 수 있습니다. PostgreSQL은 견고성, 고급 기능, 엔터프라이즈 적합성으로 높은 평가를 받고 있어 Mattermost의 데이터베이스로 선택되었습니다.

MariaDB는 MySQL과 상당 부분 호환되지만 추가적인 복잡성과 잠재적인 비일관성을 가져오며, Mattermost 개발팀은 데이터베이스 지원 범위를 제한함으로써 이를 피하고자 합니다.

이러한 이유로 MariaDB에서 PostgreSQL로의 직접 마이그레이션도 지원하지 않습니다. Oracle이 제공하는 MariaDB에서 MySQL로 마이그레이션하는 방법 문서를 PostgreSQL 마이그레이션의 출발점으로 활용할 수 있습니다.

문제 해결

MySQL의 지원되지 않는 인증 방식

MySQL v8 인증 때문에 오류가 발생한다면 pgloader의 알려진 문제와 관련이 있을 수 있습니다. 해결 방법은 MySQL 구성에서 기본 인증 방식을 mysql_native_password로 설정하는 것입니다. 이를 위해 mysql.cnf 파일에 default-authentication-plugin=mysql_native_password 값을 추가하세요. 또한 사용자가 이 인증 방식을 사용하도록 업데이트하는 것도 잊지 마세요.

ALTER USER '<mysql_user>'@'%' IDENTIFIED WITH mysql_native_password BY '<mysql_password>';

pgloader 명령 실행 중 오류

pgloader 명령을 실행하는 중 오류가 발생하면, 두 데이터베이스에 모두 접근할 수 있는지, 그리고 사용자가 데이터베이스에 접근할 수 있는 권한을 갖고 있는지 확인하세요. pgloader 명령 실행 중 오류가 있다면 마이그레이션을 계속 진행하지 마세요.

다음 섹션에서는 pgloader 명령 실행 중 마주칠 수 있는 일반적인 오류의 해결 방법을 설명합니다.

JSON 타입에 대한 잘못된 입력 구문

다음과 유사한 오류 메시지가 표시되는 경우:

ERROR Database error 22P02: invalid input syntax for type json

MySQL 데이터베이스의 데이터가 유효한 JSON 형식이 아닙니다. MySQL 데이터베이스의 데이터를 유효한 JSON 형식으로 수정하면 이 문제를 해결할 수 있습니다. 어떤 행이 문제를 일으키는지 확인하려면 다음 쿼리를 실행하세요(<table_name>과 <column_name>은 pgloader 출력에 표시된 실제 테이블·컬럼 이름으로 바꿉니다).

SELECT * FROM <table_name> WHERE JSON_VALID(<column_name>) = 0;

위 쿼리로 문제가 되는 데이터를 찾아 유효한 JSON 형식으로 수정할 수 있습니다. 데이터를 수정한 뒤 pgloader 명령을 다시 실행하세요.

컬럼 또는 테이블을 찾지 못함

다음과 유사한 오류 메시지가 표시되는 경우:

pgloader failed to find column

PostgreSQL 데이터베이스에 해당 컬럼이나 테이블이 없습니다. 올바른 버전의 Postgres 스키마를 생성했는지 확인하면 이 문제를 해결할 수 있습니다. 스키마를 다시 생성한 뒤 pgloader 명령을 다시 실행하세요.

ECASE 표현식을 통과함

다음과 유사한 오류 메시지가 표시되는 경우:

ERROR mysql: 76 fell through ECASE expression.

이는 pgloader의 알려진 문제입니다. pgloader를 소스에서 직접 컴파일하거나, Mattermost의 도커 이미지로 pgloader를 실행해 이 문제를 피할 수 있습니다. 자세한 내용은 pgloader 설치를 참고하세요.

Mattermost가 PostgreSQL 데이터베이스에 연결하지 못함

Mattermost가 PostgreSQL 데이터베이스에 연결하지 못하는 문제가 발생하면, PostgreSQL 서버가 실행 중이고 데이터베이스에 접근할 수 있는지 확인하세요. pgloader 명령 실행 중 오류가 있었다면 스키마 이름을 public으로 되돌리지 못했거나 search_path를 복원하지 못했을 수 있습니다. 다음 명령을 실행해 스키마 이름을 public으로 되돌리고 search_path를 수동으로 복원할 수 있습니다.

1. sudo -u postgres psql로 PostgreSQL에 연결합니다.
2. \c mattermost로 mattermost 데이터베이스를 선택합니다. SELECT current_database();를 실행해 올바른 데이터베이스를 사용하고 있는지 확인하세요. 이 명령은 mattermost를 출력해야 합니다.

3. 스키마 이름 변경을 되돌립니다(선택 사항).

   ALTER SCHEMA <schema_name> RENAME TO public;

또한 데이터베이스 사용자가 public 스키마에 기본 접근 권한을 갖도록 설정되어 있는지 확인하세요. 다음 명령으로 확인할 수 있습니다.

4. mmuser의 search_path를 설정합니다.

   ALTER USER mmuser SET search_path TO "$user", public;

5. 연결을 종료한 뒤 psql 서버에 다시 연결합니다.

6. search_path가 올바르게 설정되었는지 확인합니다.

   SHOW search_path;

   결과로 "$user", public이 반환되어야 합니다.

7. 문제가 계속되면 다음도 실행하세요.

   SELECT pg_catalog.set_config('search_path', '"$user", public', false);

PostgreSQL에서 스키마 접근 시 권한 문제

2단계에서 다음과 유사한 권한 문제가 보고된다면:

An Error Occurred: could not check schema owner: the user “mmuser” is not owner of the “public” schema

PostgreSQL의 mmuser 사용자가 해당 스키마의 소유자인지 확인하세요.

1. sudo -u postgres psql로 PostgreSQL에 연결합니다.
2. \c mattermost로 mattermost 데이터베이스를 선택합니다. SELECT current_database();를 실행해 올바른 데이터베이스를 사용하고 있는지 확인하세요. 이 명령은 mattermost를 출력해야 합니다.

3. 다음 명령을 실행합니다.

   ALTER SCHEMA public OWNER TO mmuser;
   GRANT USAGE, CREATE ON SCHEMA public TO mmuser;

그런 다음 2단계의 명령을 다시 실행하세요.

마이그레이션 후 인커밍 웹훅의 채널 이름이 대소문자를 구분하게 됨

MySQL에서 PostgreSQL로 마이그레이션한 뒤에는, 이전에 대소문자가 섞인 채널 이름(예: "Tech-Talk")으로 정상 동작하던 인커밍 웹훅이 다음 오류와 함께 실패합니다.

GetChannelByName: Channel does not exist.

이는 Mattermost가 대문자가 포함된 채널 생성을 허용하지 않기 때문입니다. 새 채널 이름은 모두 소문자만 포함해야 합니다. 또한 MySQL은 채널 이름을 매칭할 때 대소문자를 구분하지 않지만 PostgreSQL은 구분합니다. 즉, MySQL의 관대한 대소문자 무시 매칭에서 동작하던 웹훅 페이로드가 PostgreSQL의 엄격한 대소문자 구분 매칭에서는 실패합니다. 드물게 예전에 만들어진 채널이 대소문자가 섞인 이름으로 데이터베이스에 남아 있을 수 있습니다. 이런 채널은 유효하지 않은 것으로 간주되며, 채널 헤더 업데이트 같은 작업을 수행할 때 문제를 일으킬 수 있습니다.

해결 방법:

모든 웹훅 페이로드가 소문자 채널 이름만 사용하도록 수정하세요.

예방:

PostgreSQL로 마이그레이션하기 전에 다음을 수행하세요.

1. 인커밍 웹훅을 점검해 페이로드에서 대소문자가 섞인 채널 이름을 사용하는 항목을 수정합니다.
2. 이전 버전에서 생성되었을 수 있는, 대소문자가 섞인 이름의 레거시 채널이 있는지 확인합니다.
3. 문제를 방지하기 위해 대소문자가 섞인 채널의 이름을 소문자로 변경하는 것을 고려합니다.

이는 PostgreSQL에서 예상되는 동작이며 Mattermost의 채널 이름 요구 사항을 반영한 것입니다.

레거시 Boards 테이블로 인한 마이그레이션 오류

MySQL에서 PostgreSQL로 데이터베이스를 마이그레이션하는 동안 스키마 비교 도구(예: dbcmp)를 사용할 때 다음 오류가 발생할 수 있습니다.

error during comparison: no pk defined for table: focalboard_file_info

이는 대개 더 이상 사용되지 않는 구버전 Boards의 레거시 테이블과 관련이 있습니다. Boards 버전 8.0.0 이상을 사용 중이라면 이 테이블들은 더 이상 필요하지 않으며 마이그레이션 과정에서 무시해도 됩니다.

적용 대상:

• Boards 버전 8.0.0 이상
• 모든 스테이징, UAT, QA, 운영 환경

해결 방법:

Boards 버전 8.0.0 이상을 사용 중이라면, 독립 실행형 버전에서만 사용되던 다음 레거시 테이블은 안전하게 무시할 수 있습니다.

• focalboard_file_info - 독립 실행형 버전에서 사용되었으며, 플러그인 및 이후 버전에서는 더 이상 관련이 없습니다. 보드에 업로드된 파일과 첨부 파일을 저장합니다.
• focalboard_sessions - 독립 실행형 버전에서 사용되었습니다. 보드의 사용자 로그인 세션을 추적합니다.
• focalboard_teams - 독립 실행형 버전에서 사용되었습니다. 이후 버전에서는 사용되지 않는 레거시 팀 매핑입니다. 팀 보드 설정과 권한을 저장합니다.
• focalboard_users - 독립 실행형 버전에서 사용되었습니다. 보드의 사용자 환경 설정을 저장합니다.

현재 환경에서 이 테이블들은 비어 있거나 사용되지 않을 수 있습니다. 그렇다면 PostgreSQL로 마이그레이션할 필요가 없습니다.

지원 문의

자사 Mattermost 배포에 맞춘 안내가 필요한 Mattermost 고객은 Mattermost 전문가에게 문의할 수 있습니다.