🐬
MySQLへのスキーマ適用 - Workflow Engine「Temporal」(3)

2025/02/10に公開
MySQL
workflow
temporal
tech
Temporal では、データの保存先としてMySQLを利用することが出来ます。この記事では本番環境や検証環境におけるMySQLのセットアップ方法を紹介したいと思います。

 今回扱うもの今回扱うものは、MySQLと temporal-admin-tools になります。

 データベースとユーザーの作成Temporalでは通常、2つのデータベースを作成する必要があります。
メインのTemporalデータベース
Visibilityデータベース
また、それぞれのデータベースに対して、2種類のユーザーを作っておく必要があります。
スキーマを操作できる管理用ユーザー
データを操作できるアプリケーション用ユーザー
-- データベースの作成
CREATE DATABASE IF NOT EXISTS temporal CHARACTER SET utf8mb4;
CREATE DATABASE IF NOT EXISTS temporal_visibility CHARACTER SET utf8mb4;

-- ユーザーの作成
CREATE USER 'temporal_admin'@'%' IDENTIFIED BY '******';
CREATE USER 'temporal_app'@'%' IDENTIFIED BY '******';

-- 管理用ユーザーにはデータベースに対する全権限を付与
-- (必要最小限の権限に関する情報は見つけることができなかった)
GRANT ALL PRIVILEGES ON temporal.* TO 'temporal_admin'@'%';
GRANT ALL PRIVILEGES ON temporal_visibility.* TO 'temporal_admin'@'%';

-- アプリケーション用ユーザに必要と思われる権限を付与
-- (必要最小限の権限に関する情報は見つけることができなかった)
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, CREATE TEMPORARY TABLES, LOCK TABLES ON temporal.* TO 'temporal_app'@'%';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, CREATE TEMPORARY TABLES, LOCK TABLES ON temporal_visibility.* TO 'temporal_app'@'%';

 DBスキーマのセットアップDBスキーマのセットアップには、temporal-admin-toolsを用います。

temporal-admin-toolsは、Temporalの管理を行うためのコンテナイメージで、管理用コマンドやスキーマの定義ファイルが含まれています。
さて、Temporal Server にバージョンがあるように、DBスキーマにもバージョンがあります。

DBスキーマのバージョンは、Temporal のバージョンとは別で管理されていますが、互換性のある組み合わせは限定されます。
なんだか、バージョンの対応付を考慮するのが大変そうですが、安心してください。

たとえば、temporal-admin-tools 1.25.x は、マイナーバージョンが同じ Temporal Server 1.25.x を対象とした管理用コンテナで、そのバージョンに適用できるDBスキーマ定義ファイルが含まれています。

なので、利用する Temporal Server と同じバージョンの temporal-admin-tools を使ってセットアップを行えば、自動的に適切なバージョンのスキーマが適用されます。
今回は、Temporal Server 1.25.0 を利用するため、temporal-admin-tools 1.25.0 を用いてセットアップを行いましょう。
前回 示したcompose.ymlを用いて、temporal-admin-toolsを利用します。今回はAWSのRDSに対してセットアップするものとして、接続に証明書バンドルを用いています。
# コンテナに入る
docker compose exec temporal-admin-tools /bin/bash

# カレントディレクトリはここ
pwd
# /etc/temporal

# temporal db にあてるマイグレーションファイル
# ディレクトリ内のスキーマバージョンは、データベース構造への増分変更を表している。 
ls ./schema/mysql/v8/temporal/versioned/
# v1.0   v1.1   v1.10  v1.11  v1.12  v1.13  v1.14  v1.2   v1.3   v1.4   v1.5   v1.6   v1.7   v1.8   v1.9

# temporal visibility にあてるマイグレーションファイル
ls ./schema/mysql/v8/visibility/versioned/
# v1.0  v1.1  v1.2  v1.3  v1.4  v1.5  v1.6

# 証明書バンドルをダウンロードする
# 今回はAWSのRDSに対してセットアップするものとして、接続に証明書バンドルを使用。
curl "https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem" > /tmp/global-bundle.pem

# セットアップに必要な管理用ユーザーで接続できることを確認
mysql --ssl-ca=/tmp/global-bundle.pem -u temporal_admin -h xxxx.xxxx.ap-northeast-1.rds.amazonaws.com -P 3306 -p 

# temporal dbのセットアップ
# SQL_DATABASEでメインのTemporalデータベースであることを指定
SQL_DATABASE=temporal temporal-sql-tool \
  --tls \
  --tls-ca-file /tmp/global-bundle.pem \
  --ep xxxx.xxxx.ap-northeast-1.rds.amazonaws.com \
  -p 3306 \
  -u temporal_admin \
  -pw ***** \
  --pl mysql8 \
  --db temporal \
  setup-schema -v 0.0

SQL_DATABASE=temporal temporal-sql-tool \
  --tls \
  --tls-ca-file /tmp/global-bundle.pem \
  --ep xxxx.xxxx.ap-northeast-1.rds.amazonaws.com \
  -p 3306 \
  -u temporal_admin \
  -pw ***** \
  --pl mysql8 \
  --db temporal \
  update-schema -d ./schema/mysql/v8/temporal/versioned/

# temporal visibilityのセットアップ
# SQL_DATABASEでVisibilityデータベースであることを指定
SQL_DATABASE=temporal_visibility temporal-sql-tool \
  --tls \
  --tls-ca-file /tmp/global-bundle.pem \
  --ep xxxx.xxxx.ap-northeast-1.rds.amazonaws.com \
  -p 3306 \
  -u temporal_admin \
  -pw ***** \
  --pl mysql8 \
  --db temporal_visibility \
  setup-schema -v 0.0

SQL_DATABASE=temporal_visibility temporal-sql-tool \
  --tls \
  --tls-ca-file /tmp/global-bundle.pem \
  --ep xxxx.xxxx.ap-northeast-1.rds.amazonaws.com \
  -p 3306 \
  -u temporal_admin \
  -pw ***** \
  --pl mysql8 \
  --db temporal_visibility \
  update-schema -d ./schema/mysql/v8/visibility/versioned/

 スキーマのアップグレードについてTemporal Server のバージョンアップを行う場合、スキーマもバージョンアップを行う必要がある場合があります。ここでは、その手順について紹介します。

 考慮事項Temporal Server をアップグレードする際には、以下の 2 つの重要な点を考慮する必要があります。
順序通りのアップグレード： Temporal Server は 順序通り にアップグレードする必要があります。つまり、現在のバージョンが (v1.n.x) の場合、次のアップグレードは (v1.n+1.x) または最も近い後続のバージョンにする必要があります。この手順を繰り返し、目的のバージョンに到達するまで順次アップグレードしていきます。
データの互換性： アップグレードの過程で、Temporal Server は既存のデータを新しいバージョンのデータフォーマットに合わせて更新または再構成します。ただし、Temporal Server は 連続する 2 つのマイナーバージョン間 のみで後方互換性を保証します。そのため、バージョンを飛ばしてアップグレードすると、古いデータフォーマットが読み取れなくなる可能性があります。もし以前のデータフォーマットが新しいフォーマットに変換できない場合、アップグレードは失敗します。
Upgrade the Temporal Server より

 Temporal Server のアップグレード手順Temporal Server をアップグレードする際は、次の手順で行っていきます。

スキーマアップグレードが必要か確認： 対象バージョンのリリースノートを確認し、スキーマアップグレードが必要かどうかを確認します。

スキーマアップグレード： スキーマアップグレードが必要な場合、Temporal Server をアップグレードする前に、temporal-sql-tool コマンドを使用して必要なスキーマ変更を適用します。

Temporal Server をアップグレード： データベーススキーマが更新されたら、Temporal Serverを次の連続したバージョンにアップグレードします。

反復アップグレード： 希望のTemporal Serverバージョンになるまで、このプロセス（ステップ1と2と3）を繰り返し続けます。

 まとめこの記事では、Temporalで利用するMySQLのセットアップ方法について説明しました。具体的には以下の内容を取り上げました。
データベースとユーザーの作成方法
temporal-admin-toolsを使用したスキーマの適用方法
バージョンアップ時の考慮事項と手順
MySQLを使用する場合、適切なセットアップとバージョン管理が重要です。この記事で紹介した手順に従うことで、安全かつ確実なTemporalの運用が可能になります。

 Workflow Engine 「Temporal」の記事一覧
 Workflow Engine 「Temporal」の記事一覧脱データ不整合!? Workflow Engine「Temporal」の魅力
開発環境構築と実装例 - Workflow Engine「Temporal」(2)
MySQLへのスキーマ適用 - Workflow Engine「Temporal」(3)
Kubernatesクラスタでの構築 - Workflow Engine「Temporal」(4)
今回扱うもの

データベースとユーザーの作成

DBスキーマのセットアップ

スキーマのアップグレードについて

考慮事項

Temporal Server のアップグレード手順

まとめ

Workflow Engine 「Temporal」の記事一覧

Workflow Engine 「Temporal」の記事一覧

Discussion
