Liquibase

CRAIDでブリッジエンジニアをしているKakeyaです。以前、セブでインターン中にお世話になった現地エンジニアMarkさんが投稿した記事を翻訳しましたので、当記事で紹介いたします。

こちらが元記事になりますので是非読んでみてください。
翻訳元記事(オフショア子会社Fullspeed Technologies Inc.の技術ブログ)

Liquibase
まとめ

Liquibaseは、データベーススキーマの変更を追跡、管理、適用するためのオープンソースのデータベースライブラリです。開発者は、既にデプロイされているものを知る必要なく、特定のバージョンの変更を容易にデプロイ、ロールバックすることができます。LiquibaseはXML、SQL、YAML、JSON形式をサポートしているため、特定のプログラミング言語を知っている必要はありません。唯一の前提条件は、マシン上でJavaが動作していることです。

インストール

JavaをローカルまたはLiquibaseを実行する場所にインストールします。
OSに基づいてインストーラをダウンロードします。
Liquibaseをインストールします。

加筆：Javaのインストールは必須ではありません。また、Liquibaseのインストールに関してはこちらをご参照ください。

プロジェクトの作成

Liquibaseのマイグレーションファイルと、Liquibaseの設定が存在するプロジェクトフォルダを作成します。

Liquibaseを使う際、マイグレーションファイルをすべて1つのサブフォルダに入れ、そのサブフォルダ内のマイグレーションファイルを1つのchangeLogFileとしてインクルード(参照)するのが良いプラクティスとなっています。なぜなら、liquibase.propertiesファイル内では参照できるchangeLogFileが１つしか指定できないからです。

加筆：つまり、複数のマイグレーションファイルを個別にliquibase.propertiesで指定するのではなく、1つのマスターchangeLogFileを作成し、その中でサブフォルダ内の他のマイグレーションファイルを参照する形にするということです。このようにすることで、マイグレーションファイルをまとめて管理でき、liquibase.propertiesの記述も単純化できます。マイグレーション作業の見通しがよくなり、ファイルの追加・削除が容易になるというメリットがあります。

プロジェクトストラクチャーの例

project_folder
    - migration
    - parameters
    mysql-connector.jar
    liquibase.properties
    changelog-master.yaml

1. まず、changelog-master.yamlというマスターchangeLogファイルを作成します。

databaseChangeLog:
  - includeAll:
   path: migration/

加筆：このファイルには、マイグレーションファイルが格納されているディレクトリ（この例ではmigrationディレクトリ）を指定します。

2. 次に、MavenリポジトリからMySQLデータベース用のコネクタをダウンロードします。この例ではMySQLを使用するので、mysql-connectorと検索し、適切なバージョンのjarファイルをダウンロードします。

3. ダウンロードしたjarファイルをプロジェクトディレクトリに移動させ、liquibase.propertiesファイル内のclasspathを適切に更新します。

4. 最後に、Liquibaseを設定します。liquibase.propertiesという新しいテキストファイルを作成します。

driver: com.mysql.cj.jdbc.Driver
     url: <db url connection>
     username: <user>
     password: <password>
     changeLogFile: changelog-master.yaml
     classpath: mysql-connector-java-8.0.21/mysql-connector-java-8.0.21.jar

既存のデータベースのスナップショットを取得する

コマンド : liquibase --changeLogFile=mydatabase_changelog.xml generateChangeLog

既存のデータ量によっては、このコマンドの実行に時間がかかる可能性があります。

生成されたファイルのサンプル：

<?xml version="1.0" encoding="UTF-8"?>  
<databaseChangeLog  
  xmlns="http://www.liquibase.org/xml/ns/dbchangelog"  
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
  xmlns:pro="http://www.liquibase.org/xml/ns/pro"  
  xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.4.xsd
      http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-4.5.xsd">  
    <changeSet  author="lb-generated"  id="1185214997195-1">  
        <createTable  name="BONUS">  
            <column  name="NAME"  type="VARCHAR2(15)"/>  
            <column  name="JOB"  type="VARCHAR2(255)"/>  
            <column  name="SAL"  type="NUMBER(255)"/>
        </createTable>  
    </changeSet>
    <changeSet  author="lb-generated"  id="1185214997195-2">  
        <createTable  name="DEPT">  
            <column  name="DEPTNO"  type="INTEGER"/>  
            <column  name="DNAME"  type="VARCHAR2(15)"/>  
            <column  name="LOC"  type="VARCHAR2(255)"/>  
        </createTable>  
    </changeSet>
    <changeSet  author="lb-generated"  id="1185214997195-3">
         <createView fullDefinition="false" viewName="myView2">SELECT "DEPT".DEPTNO,
    "DEPT".DNAME
   FROM "DEPT";</createView>
    </changeSet>
    <changeSet  author="lb-generated"  id="1185214997195-4">  
        <pro:createFunction functionName="myFunction" path="objects/function/myFunction.sql" relativeToChangelogFile="true"/>  
    </changeSet>
</databaseChangeLog>

マイグレーションファイルの作成

Liquibaseでは、JSON、YAML、XML、SQLフォーマットからマイグレーションファイルのフォーマットを選択できます。この例では、migrationフォルダ内にマイグレーションファイルを作成します。

マイグレーションファイルのフォーマットについては、Liquibaseの公式ドキュメントで詳しく説明されています。

YAMLフォーマットでのサンプルは以下のとおりです：

databaseChangeLog:
  - changeSet:
      id: modify_table_datatype
      author: mark.remedio@fullspeedtechnologies.com
      validCheckSum: ANY
      comment: Modify datatype of the tabe field
      changes:
        - tagDatabase:
            tag: modify-column-datatype-in-table
        - modifyDataType:
            columnName: column_name
            newDataType: varchar(255)
            schemaName: db_name
            tableName: table_name
      rollback:
        - modifyDataType:
            columnName: column_name
            newDataType: varchar(50)
            schemaName: db_name
            tableName: table_name

加筆：このマイグレーションファイルでは、テーブルのカラムのデータ型を変更するための変更セットが定義されています。

changeSetブロックには、この変更セットに関する情報が含まれています。
- idはこの変更セットを一意に識別するID
- authorは変更を加えた人の情報
- validCheckSumは変更セットの内容が変更されたかどうかをチェックする際に使用されるチェックサム
- commentはこの変更セットの説明
changesブロックには、実際に行う変更の内容が記述されています。
- tagDatabaseは変更セットにタグを付ける
- modifyDataTypeはテーブルのカラムのデータ型を変更する
rollbackブロックには、この変更セットをロールバック(元に戻す)する際の処理が記述されています。