업그레이드 준비

대부분의 경우 Mattermost 서버 업그레이드는 몇 분이면 끝납니다. 다만 설치 규모와 복잡도, 그리고 업그레이드 이전 버전 등 여러 요인에 따라 더 오래 걸릴 수 있습니다. 업그레이드를 계획할 때는 현재 사용 중인 데이터베이스와 운영 체제 버전이 여전히 지원되는지 확인하는 것이 좋습니다. 자세한 내용은 소프트웨어 및 하드웨어 요구 사항 페이지에서 확인할 수 있습니다.

업그레이드 모범 사례

Mattermost는 일반적으로 잠금이 발생하지 않고 하위 호환성을 유지하는 마이그레이션을 지향합니다. 이 하위 호환성 보장은 직전 ESR 버전까지만 적용됩니다. 예를 들어 ESR1, ESR2, ESR3 세 가지 ESR 버전이 있다면 ESR1에서 ESR2로, 그다음 ESR2에서 ESR3으로 업그레이드하는 경로는 하위 호환성이 보장되지만, ESR1에서 ESR3으로 바로 업그레이드하는 경로는 보장되지 않습니다.

업그레이드가 지연된 경우에는 가장 가까운 ESR 버전으로 먼저 업그레이드한 뒤 그다음 ESR로 넘어가는 방식을 권장합니다. 최신 버전으로 곧바로 업그레이드하려고 하지 마세요. 업그레이드 도중 클러스터 내 이전 버전 노드와의 하위 호환성이 깨질 수 있습니다.

Mattermost v7.1로 업그레이드

Mattermost v7.1은 새 컬럼과 해당 인덱스 형태의 스키마 변경을 도입합니다. 이 스키마 변경에 대한 테스트 결과는 다음과 같습니다.

• PostgreSQL 게시물 1,200만 건, 반응 250만 건 - 약 1분 18초(인스턴스: db.r5.2xlarge)

업그레이드 전에 다음 SQL 쿼리를 실행할 수 있으며, 이 쿼리는 Reactions 테이블에 대한 잠금을 획득합니다. 이 시간 동안 사용자가 남긴 반응은 마이그레이션이 완료될 때까지 데이터베이스에 반영되지 않습니다. 이 작업은 하위 호환성이 완전히 유지됩니다.

연결 콜레이션과 테이블 콜레이션이 서로 다르면 Illegal mix of collations 오류가 발생할 수 있습니다. 이 오류를 해결하려면 연결과 테이블에 동일한 콜레이션을 설정하세요. 콜레이션은 연결, 데이터베이스, 테이블, 컬럼 등 여러 수준에 존재하며, 데이터베이스 관리자가 객체마다 서로 다른 콜레이션 수준을 설정했을 수 있습니다.

ALTER TABLE reactions ADD COLUMN IF NOT EXISTS channelid varchar(26) NOT NULL DEFAULT '';

UPDATE reactions SET channelid = COALESCE((select channelid from posts where posts.id = reactions.postid), '') WHERE channelid='';

CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_reactions_channel_id on reactions (channelid);

Mattermost v6.7로 업그레이드

Mattermost v6.7은 새 인덱스 형태의 스키마 변경을 도입합니다. 이 스키마 변경에 대한 테스트 결과는 다음과 같습니다.

• Postgres 게시물 700만 건 - 약 9초(인스턴스: db.r5.xlarge)

무중단 업그레이드를 원한다면 업그레이드 전에 이 인덱스를 미리 적용할 수 있습니다.

CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_posts_create_at_id on posts(createat, id);

이 작업은 하위 호환성이 완전히 유지되며, 테이블 잠금을 획득하거나 테이블에 대한 기존 작업에 영향을 주지 않습니다.

Mattermost v6.0으로 업그레이드

Mattermost 서버 v6.0 업그레이드는 대규모 데이터베이스 스키마 변경을 수행하므로 데이터셋 크기에 따라 시작 시간이 길어질 수 있습니다. v6.0에서는 무중단 업그레이드가 불가능하지만, 마이그레이션 과정에서 기울이는 노력에 따라 중단 시간을 상당 부분 줄일 수 있습니다.

업그레이드 전에 쿼리를 미리 실행하면 중단 시간을 일부 줄일 수 있습니다. 다만 일부 쿼리는 여전히 테이블 전체 잠금을 유발할 수 있으며, 쿼리가 실행되는 동안 Mattermost를 읽기 전용 모드로 두어야 합니다.

다음을 강력히 권장합니다.

• 마이그레이션의 영향을 줄일 수 있도록 업무 시간 외에 유지 보수 시간대를 설정하세요.
• 필요할 경우 이전 데이터베이스 스냅숏을 복원할 수 있도록 데이터베이스 백업을 확보하세요.
• Mattermost v6.0 업그레이드를 시도하기 전에 먼저 최신 Extended Support Release(ESR)로 인스턴스를 업그레이드하세요.

v6.0 데이터베이스 스키마 마이그레이션

Mattermost v6.0은 데이터베이스와 애플리케이션 성능을 모두 개선하기 위해 여러 데이터베이스 스키마 변경을 도입합니다. 이 업그레이드는 대규모 데이터베이스 스키마 변경을 수행하므로 데이터셋 크기에 따라 시작 시간이 길어질 수 있습니다. Mattermost는 게시물 1,000만 건 이상과 7,200만 건 이상의 실제 데이터셋을 사용해 지원되는 PostgreSQL 데이터베이스 드라이버에서 광범위한 테스트를 수행했습니다.

마이그레이션 과정에서 실행되는 다음 쿼리는 실행되는 동안 데이터베이스 CPU 사용량과 쓰기 작업 제한에 상당한 영향을 줍니다.

ALTER TABLE posts ALTER COLUMN props TYPE jsonb USING props::jsonb; (약 11분)

PostgreSQL 쿼리 전체 목록과 각 쿼리의 영향 및 소요 시간은 Mattermost v6.0 DB 스키마 마이그레이션 분석을 참고하세요.

v5.35 이전 릴리스에서 업그레이드

Mattermost v5.35 이전 릴리스에서 v6.0으로 업그레이드하는 고객은 v5.35에서 도입된 백엔드 데이터베이스 아키텍처로 인해 상당한 중단 시간이 발생할 수 있습니다. 이 업그레이드 경로는 대규모 설치 환경에는 권장하지 않습니다. Mattermost v6.0으로 업그레이드하기 전에 먼저 최신 Extended Support Release(ESR)로 업그레이드할 것을 권장합니다. 자세한 내용은 지원 종료된 레거시 릴리스 문서를 참고하세요.

Mattermost v5.0 이전 버전에서 업그레이드하는 경우 v6.0으로 곧바로 업그레이드할 수 없습니다. 대신 최신 ESR로 먼저 업그레이드한 뒤 v6.0으로 업그레이드하는 식으로 단계를 나누어 진행할 것을 강력히 권장합니다. 첫 번째 업데이트 단계에서는 v5.0 릴리스에서 도입된 바이너리 변경에 맞게 서비스 파일도 수정해야 합니다. 실행 디렉터리는 Mattermost 기본 디렉터리(예: /opt/mattermost)를 가리켜야 하고, 바이너리는 mattermost 바이너리(예: /opt/mattermost/bin/mattermost)를 가리켜야 합니다.

업그레이드에 영향을 줄 수 있는 마이그레이션을 미리 파악할 수 있도록 그 사이의 모든 중간 릴리스 버전에 대한 주요 업그레이드 참고 사항을 반드시 검토하세요.

Failed to alter column type. It is likely you have invalid JSON values in the column. Please fix the values manually and run the migration again.","caller":"sqlstore/store.go:854","error":"pq: unsupported Unicode escape sequence

ALTER TABLE posts ALTER COLUMN props TYPE jsonb USING props::jsonb;
ALTER TABLE channelmembers ALTER COLUMN notifyprops TYPE jsonb USING notifyprops::jsonb;
ALTER TABLE jobs ALTER COLUMN data TYPE jsonb USING data::jsonb;
ALTER TABLE linkmetadata ALTER COLUMN data TYPE jsonb USING data::jsonb;
ALTER TABLE sessions ALTER COLUMN props TYPE jsonb USING props::jsonb;
ALTER TABLE threads ALTER COLUMN participants TYPE jsonb USING participants::jsonb;
ALTER TABLE users ALTER COLUMN props TYPE jsonb USING props::jsonb;
ALTER TABLE users ALTER COLUMN notifyprops TYPE jsonb USING notifyprops::jsonb;
ALTER TABLE users ALTER COLUMN timezone TYPE jsonb USING timezone::jsonb;

SELECT COUNT(*) FROM TableName WHERE ColumnName LIKE '%\u0000%';

UPDATE TableName SET ColumnName = regexp_replace(ColumnName, '\\u0000', '', 'g') WHERE ColumnName LIKE '%\u0000%';

고가용성 클러스터 기반 배포 업그레이드

고가용성 클러스터 기반 환경에서는 v6.0 업그레이드를 위한 중단 시간을 예정해 두어야 합니다. 데이터베이스 크기와 구성에 따라 v6.0으로의 마이그레이션에 상당한 시간이 걸릴 수 있으며, 게시물 테이블이 잠겨 마이그레이션이 끝날 때까지 사용자가 메시지를 보내거나 받지 못할 수도 있습니다.

사용 중인 버전에서 업그레이드하기 전이나 후에 취해야 할 조치를 파악할 수 있도록 고가용성 클러스터 기반 배포 업그레이드 가이드와 주요 업그레이드 참고 사항을 반드시 검토하세요.