Jira Version Upgrade 8.x to 9.x (req. MySQL 8.0)

이 글은 Atlassian Jira LTS 버전 기준 및 Docker 기반으로 진행하며 Atlassian Docs를 참고하여 작성하였습니다.

Jira 업그레이드 전 점검사항

Jira 9.x 버전으로 업그레이드 하기 위해서는 Atlassian Docs에서 지원 플랫폼을 확인할 수 있습니다.

주요 사항을 보자면
Jira 8.x 버전에서 사용 가능했던 MySQL 5.7 버전이 더 이상 지원되지 않고 MySQL 8.0 버전으로 업그레이드를 해야합니다.

기존 MySQL 5.7 버전에서 MySQL 8 버전으로 업그레이드 하는 과정도 설명하겠습니다.

docker-compose.ymal

본 가이드에서 사용될 파일입니다.

version: '3'
services:
  jira:
    image: atlassian/jira-software:8.20.18
    container_name: jira
    depends_on:
      - jira-db
    ports:
      - "8080:8080"
    volumes:
      - /var/atlassian/application-data/jira:/var/atlassian/application-data/jira

  jira-db:
    image: mysql:5.7
    container_name: jira-db
    volumes:
      - /root/jira-db:/var/lib/mysql
      # 테스트를 위해 신규 DB 설정
      #- /root/jira-db-config:/etc/mysql/conf.d
    environment:
      MYSQL_ROOT_PASSWORD: "admin"

신규 Jira 및 DB(MySQL 5.7)를 사용하여 테스트 하기 위한 가이드

신규로 Jira 컨테이너를 MySQL5.7 버전과 연결할 때 아래 사진과 같이 오류가 발생할 수 있습니다.

이를 방지하고자 아래 파일들의 설정을 적용합니다. (신규 설치 기준)

[mysqld]
default-storage-engine=INNODB
innodb_default_row_format=DYNAMIC
innodb_large_prefix=ON
innodb_file_format=Barracuda
innodb_log_file_size=2G
sql_mode = NO_AUTO_VALUE_ON_ZERO

<?xml version="1.0" encoding="UTF-8"?>
<jira-database-config>
  <name>defaultDS</name>
  <delegator-name>default</delegator-name>
  <database-type>mysql</database-type>
  <jdbc-datasource>
    <url>jdbc:mysql://dbserver:3306/jiradb?useUnicode=true&amp;amp;characterEncoding=UTF8&amp;amp;sessionVariables=default_storage_engine=InnoDB</url>
    <driver-class>com.mysql.jdbc.Driver</driver-class>
    <username>jiradbuser</username>
    <password>password</password>
    <pool-min-size>20</pool-min-size>
    <pool-max-size>20</pool-max-size>
    <pool-max-wait>30000</pool-max-wait>
    <pool-max-idle>20</pool-max-idle>
    <pool-remove-abandoned>true</pool-remove-abandoned>
    <pool-remove-abandoned-timeout>300</pool-remove-abandoned-timeout>
    
    <validation-query>select 1</validation-query>
    <validation-query-timeout>3</validation-query-timeout>
    <min-evictable-idle-time-millis>60000</min-evictable-idle-time-millis>
    <time-between-eviction-runs-millis>300000</time-between-eviction-runs-millis>
  
    <pool-test-while-idle>true</pool-test-while-idle>
    <pool-test-on-borrow>false</pool-test-on-borrow>    
  </jdbc-datasource>
</jira-database-config>

MySQL Connector

본 가이드에서는 아래 MySQL Connector를 사용합니다.

• mysql-connector-java-5.1.40.tar.gz
• mysql-connector-java-8.0.33.tar.gz

Jira 종료

DB를 업그레이드 해야함으로 Jira를 종료합니다.

docker-compose down

MySQL Version Upgrade(5.7 -> 8.0)

MySQL 버전 업그레이드는 Docker를 사용하기 때문에 이미지 태그만 바꿔주면 문제없이 8버전으로 업그레이드가 가능합니다.

docker-compose.yaml 수정

버전 태그만 변경하여 docker-compose restart 합니다.

version: '3'
services:
  jira:
    image: atlassian/jira-software:8.20.18
    container_name: jira
    depends_on:
      - jira-db
    ports:
      - "8080:8080"
    volumes:
      - /var/atlassian/application-data/jira:/var/atlassian/application-data/jira

  jira-db:
    image: mysql:8.0
    container_name: jira-db
    volumes:
      - /root/jira-db:/var/lib/mysql
      # 테스트를 위해 신규 DB 설정
      #- /root/jira-db-config:/etc/mysql/conf.d
    environment:
      MYSQL_ROOT_PASSWORD: "admin"

character set 및 collation 값 변경

Jira 9.x 버전대로 업그레이드 하면서 UTF8MB4를 필수적으로 사용해야합니다.
기존 사용하던 UTF8은 호환되지 않습니다.

MySQL에서 쿼리문을 통해 기존 설정된 값을 확인합니다.

use <DB-NAME>;

# DB 캐릭터 셋 및 콜레이션 확인
SELECT @@character_set_database, @@collation_database;

# 테이블 콜레이션 확인
SELECT TABLE_SCHEMA
    , TABLE_NAME
    , TABLE_COLLATION 
FROM INFORMATION_SCHEMA.TABLES;	

# 컬럼 콜레이션 확인
SELECT TABLE_NAME 
    , COLUMN_NAME 
    , COLLATION_NAME 
FROM INFORMATION_SCHEMA.COLUMNS;

이제 Character Set 및 Collate 값을 utf8mb4로 변경해줍시다.

아래 명령어는 MySQL 내부에서 직접 쿼리문을 날려 데이터베이스의 Character Set 및 Collate 값을 변경합니다.

ALTER DATABASE <DB-NAME> CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;

쿼리문 실행이 완료되었다면 아래 파일들을 생성합니다.

• table-change.sql
  특정 데이터베이스 내의 테이블을 utf8mb4와 utf8mb4_bin 로 변환하는 ALTER TABLE 문 입니다.

SELECT CONCAT('ALTER TABLE `',  table_name, '` CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;')
FROM information_schema.TABLES AS T, information_schema.`COLLATION_CHARACTER_SET_APPLICABILITY` AS C
WHERE C.collation_name = T.table_collation
AND T.table_schema = '<DB-NAME>'
AND
(
    C.CHARACTER_SET_NAME != 'utf8mb4'
    OR
    C.COLLATION_NAME != 'utf8mb4_bin'
);

• column-change.sql
  특정 데이터베이스 내의 VARCHAR 데이터 형식의 열에 대해 utf8mb4와 utf8mb4_bin 로 변환하는 ALTER TABLE 문 입니다.

SELECT CONCAT('ALTER TABLE `', table_name, '` MODIFY `', column_name, '` ', DATA_TYPE, '(', CHARACTER_MAXIMUM_LENGTH, ') CHARACTER SET utf8mb4 COLLATE utf8mb4_bin', (CASE WHEN IS_NULLABLE = 'NO' THEN ' NOT NULL' ELSE '' END), ';')
FROM information_schema.COLUMNS 
WHERE TABLE_SCHEMA = '<DB-NAME>'
AND DATA_TYPE = 'varchar'
AND
(
    CHARACTER_SET_NAME != 'utf8mb4'
    OR
    COLLATION_NAME != 'utf8mb4_bin'
);

• non-varchar.sql
  특정 데이터베이스 내의 VARCHAR 이외의 데이터 형식 열에 대해 utf8mb4와 utf8mb4_bin 로 변환하는 ALTER TABLE 문 입니다.

SELECT CONCAT('ALTER TABLE `', table_name, '` MODIFY `', column_name, '` ', DATA_TYPE, ' CHARACTER SET utf8mb4 COLLATE utf8mb4_bin', (CASE WHEN IS_NULLABLE = 'NO' THEN ' NOT NULL' ELSE '' END), ';')
FROM information_schema.COLUMNS 
WHERE TABLE_SCHEMA = '<DB-NAME>'
AND DATA_TYPE != 'varchar'
AND
(
    CHARACTER_SET_NAME != 'utf8mb4'
    OR
    COLLATION_NAME != 'utf8mb4_bin'
);

파일 생성이 완료되었다면 Linux 쉘의 mysql명령어로 sql 파일을 실행하여 Character Set 및 Collate 값을 변경합니다.

mysql -u <DB-GRANT-USER> -p <DB-NAME> < table-change.sql
mysql -u <DB-GRANT-USER> -p <DB-NAME> < column-change.sql
mysql -u <DB-GRANT-USER> -p <DB-NAME> < non-varchar.sql

Jira Version Upgrade(8.20.18 -> 9.4.14 / LTS)

MySQL 버전 업그레이드 이후 Jira 시작 전 MySQL 업그레이드 사항을 적용해야합니다.
기존 Jira에 설정 되어있던 DB 버전 정보를 변경합니다.

dbconfig.xml 수정

여기서 변경할 부분은 <database-type> 및 <driver-class> 입니다.

mysql57 -> mysql8
com.mysql.jdbc.Driver -> com.mysql.cj.jdbc.Driver

JDBC Connector 다운로드

JDBC 커넥터는 여기에서 다운로드 할 수 있습니다.
(본 가이드에서는 8.0.33 버전의 JDBC 커넥터를 사용합니다.)

docker-compose.yaml 파일 수정

Jira 이미지 태그를 변경하여 9.4.14 버전으로 시작합니다.

version: '3'
services:
  jira:
    image: atlassian/jira-software:9.4.14
    container_name: jira
    depends_on:
      - jira-db
    ports:
      - "8080:8080"
    volumes:
      - /var/atlassian/application-data/jira:/var/atlassian/application-data/jira

  jira-db:
    image: mysql:8.0
    container_name: jira-db
    volumes:
      - /root/jira-db:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: "admin"

Jira 시작

업그레이드를 위해서 docker-compose.yaml 파일을 수정하여 재기동 합니다.

docker-compose up -d

JDBC Connector 복사

docker cp 명령어로 다운로드 받은 JDBC 커넥터를 Jira Engine 디렉토리에 넣고 재기동 시켜줍니다.

docker cp mysql-connector-java-8.0.22.jar <container-id>:/opt/atlassian/jira/lib/
docker restart <container-id>

추가로

Jira 8.x 버전에서 9.x 버전으로 업그레이드 시 Index 버전이 변경됨에 따라 Index Rebuild(FULL)를 수행해야합니다.

Jira Issue가 상당히 많을 경우 Index Rebuild 시간을 최소화 하기 위한 솔루션은 아래 게시글을 참고하시면 됩니다.