マイグレーションガイド: v1.1.0

このガイドはv1.0.xからv1.1.0へのアップグレードを支援します。バージョン1.1.0にはデータ移行が必要なテナントコード処理に関する破壊的変更が含まれています。

リリース日

2026-02-03

破壊的変更の概要

変更内容	影響	必要なアクション
TENANT_COMMON の値が次に変更: 'common'	パーティションキーが次から変更: TENANT#COMMON → TENANT#common	データ移行が必要
テナントコード正規化	すべてのテナントコードが小文字に正規化	データ移行が必要な場合あり
非推奨メソッドの削除	publish(), publishPartialUpdate(), genNewSequence() を削除	メソッド呼び出しを更新

移行前チェックリスト

アップグレード前に以下を確認してください：

• DynamoDBテーブルをバックアップ
• TENANT#COMMONパーティションキーを使用しているすべてのテーブルを特定
• パーティションキーで大文字のテナントコードを使用しているすべてのテーブルを特定
• 移行のためのメンテナンスウィンドウを計画
• まず本番以外の環境で移行をテスト

破壊的変更1: TENANT_COMMON値

変更内容

SettingTypeEnum.TENANT_COMMONのenum値が変更されました：

// 変更前 (v1.0.x)
export enum SettingTypeEnum {
  TENANT_COMMON = 'COMMON',  // 大文字
  // ...
}

// 変更後 (v1.1.0)
export enum SettingTypeEnum {
  TENANT_COMMON = 'common',  // 小文字
  // ...
}

影響

これはDynamoDBのパーティションキーに影響します：

テーブル	変更前	変更後
テナント設定	TENANT#COMMON	TENANT#common
マスター設定	MASTER_SETTING#COMMON#...	MASTER_SETTING#common#...
マスターデータ	MASTER_DATA#COMMON#...	MASTER_DATA#common#...

移行手順

ステップ1: 影響を受けるデータの特定

パーティションキーにCOMMONを含むすべてのアイテムをスキャンで検索：

# AWS CLIを使用
aws dynamodb scan \
  --table-name YOUR_TABLE_NAME \
  --filter-expression "contains(pk, :common)" \
  --expression-attribute-values '{":common":{"S":"COMMON"}}' \
  --output json > common_tenant_items.json

ステップ2: 移行スクリプトの作成

// scripts/migrate-tenant-common.ts
import {
  DynamoDBClient,
  ScanCommand,
  TransactWriteItemsCommand,
} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({});
const TABLE_NAME = process.env.DATA_TABLE_NAME || 'your-table-name';

async function migrateCommonTenant() {
  console.log('TENANT_COMMON移行を開始...');

  // pkにCOMMONを含むアイテムをスキャン
  const scanResult = await client.send(new ScanCommand({
    TableName: TABLE_NAME,
    FilterExpression: 'contains(pk, :common)',
    ExpressionAttributeValues: {
      ':common': { S: 'COMMON' },
    },
  }));

  const items = scanResult.Items || [];
  console.log(`発見: ${items.length} 件のアイテムを移行`);

  // 25件ずつバッチ処理（DynamoDB制限）
  for (let i = 0; i < items.length; i += 25) {
    const batch = items.slice(i, i + 25);
    const transactItems = [];

    for (const item of batch) {
      const oldPk = item.pk.S!;
      const newPk = oldPk.replace(/COMMON/g, 'common');

      // 古いアイテムを削除
      transactItems.push({
        Delete: {
          TableName: TABLE_NAME,
          Key: {
            pk: { S: oldPk },
            sk: item.sk,
          },
        },
      });

      // 小文字のpkで新しいアイテムを作成
      const newItem = { ...item, pk: { S: newPk } };
      // tenantCodeが存在する場合は更新
      if (newItem.tenantCode?.S === 'COMMON') {
        newItem.tenantCode = { S: 'common' };
      }

      transactItems.push({
        Put: {
          TableName: TABLE_NAME,
          Item: newItem,
        },
      });
    }

    await client.send(new TransactWriteItemsCommand({
      TransactItems: transactItems,
    }));

    console.log(`バッチ移行完了: ${Math.floor(i / 25) + 1}`);
  }

  console.log('移行完了！');
}

migrateCommonTenant().catch(console.error);

ステップ3: 移行の実行

# 環境変数を設定
export DATA_TABLE_NAME=your-table-name
export AWS_REGION=ap-northeast-1

# 移行を実行（まずドライランで）
npx ts-node scripts/migrate-tenant-common.ts

ステップ4: 移行の確認

# 大文字のCOMMONを持つアイテムが残っていないことを確認
aws dynamodb scan \
  --table-name YOUR_TABLE_NAME \
  --filter-expression "contains(pk, :common)" \
  --expression-attribute-values '{":common":{"S":"#COMMON"}}' \
  --select COUNT

破壊的変更2: テナントコード正規化

変更内容

getUserContext()関数はテナントコードを小文字に正規化するようになりました：

// 変更前 (v1.0.x)
const ctx = getUserContext(invokeContext);
console.log(ctx.tenantCode); // "MY_TENANT" (Cognitoに保存されている通り)

// 変更後 (v1.1.0)
const ctx = getUserContext(invokeContext);
console.log(ctx.tenantCode); // "my_tenant" (小文字に正規化)

影響

既存のデータがパーティションキーで大文字のテナントコードを使用している場合、クエリはそのデータを見つけられません。

移行戦略

詳細な移行ガイドを参照： テナントコード正規化移行

主なオプション：

1. 戦略1: DynamoDBデータを更新 - 既存データを小文字のテナントコードを使用するように移行
2. 戦略2: カスタム正規化 - 正規化動作をオーバーライド（新規プロジェクトでは非推奨）
3. 戦略3: 段階的移行 - 移行中にデュアルリードパターンを使用

破壊的変更3: 非推奨メソッドの削除

変更内容

v1.1.0で以下の非推奨メソッドが削除されました：

パッケージ	削除されたメソッド	代替メソッド
@mbc-cqrs-serverless/core	CommandService.publish()	CommandService.publishAsync()
@mbc-cqrs-serverless/core	CommandService.publishPartialUpdate()	CommandService.publishPartialUpdateAsync()
@mbc-cqrs-serverless/sequence	SequencesService.genNewSequence()	SequencesService.generateSequenceItem()

移行手順

CommandServiceメソッド

// 変更前 (v1.0.x)
const item = await this.commandService.publish(input, opts);
const updated = await this.commandService.publishPartialUpdate(partialInput, opts);

// 変更後 (v1.1.0)
const item = await this.commandService.publishAsync(input, opts);
const updated = await this.commandService.publishPartialUpdateAsync(partialInput, opts);

SequencesServiceメソッド

// 変更前 (v1.0.x)
const sequence = await this.sequencesService.genNewSequence(dto, opts);

// 変更後 (v1.1.0)
const sequence = await this.sequencesService.generateSequenceItem(dto, opts);

これらのメソッドが削除された理由

これらのメソッドは以下の理由で非推奨化されました：

1. publish() / publishPartialUpdate(): 命名が曖昧でした。Asyncサフィックスは、これらのメソッドがDynamoDB Streamsを使用した非同期データ同期を行うことを明確にしています。

2. genNewSequence(): このメソッドは、より一貫したAPIとより良い戻り値型を提供するgenerateSequenceItem()に置き換えられました。

v1.1.0の新機能

ユーティリティ関数

テナントコード処理用の新しいユーティリティ関数が利用可能です：

import {
  normalizeTenantCode,
  isCommonTenant,
} from '@mbc-cqrs-serverless/core';

// テナントコードを正規化
const normalized = normalizeTenantCode('MY_TENANT'); // "my_tenant"

// テナントがcommonかどうかを確認
const isCommon = isCommonTenant('common'); // true
const isCommon2 = isCommonTenant('COMMON'); // true (大文字小文字を区別しない)

テストカバレッジの向上

v1.1.0には以下の包括的なテストが含まれています：

• TenantServiceメソッド（17件の新規テスト）
• SettingTypeEnum検証（7件の新規テスト）
• テナントコード正規化（70件以上のテストケース）
• テナント正規化コマンド（30件以上のテストケース）

アップグレード手順

ステップ1: 依存関係の更新

npm install @mbc-cqrs-serverless/core@1.1.0
npm install @mbc-cqrs-serverless/tenant@1.1.0
npm install @mbc-cqrs-serverless/master@1.1.0
# 必要に応じて他のパッケージを更新

ステップ2: データ移行の実行

上記の移行手順に従って：

1. TENANT_COMMON パーティションキーの変更
2. テナントコード正規化（該当する場合）

ステップ3: コードの更新（必要な場合）

ハードコードされた 'COMMON' 文字列がある場合は更新：

// 変更前
const pk = `TENANT#COMMON`;

// 変更後
import { SettingTypeEnum } from '@mbc-cqrs-serverless/tenant';
const pk = `TENANT#${SettingTypeEnum.TENANT_COMMON}`;

ステップ4: テスト

# テストスイートを実行
npm test

# ステージング環境でテスト
npm run deploy:stg

ロールバック手順

v1.0.xにロールバックする必要がある場合：

1. バックアップからDynamoDBテーブルを復元
2. パッケージをダウングレード：

   npm install @mbc-cqrs-serverless/core@1.0.26
   # など

3. アプリケーションを再デプロイ

よくある質問

Q: common tenantを使用していない場合、移行をスキップできますか？

common tenant機能（全テナント間で共有されるリソース）を使用していない場合、TENANT_COMMONデータの移行は不要かもしれません。ただし、テナントコード正規化の影響は確認してください。

Q: 移行にはどのくらい時間がかかりますか？

移行時間はデータ量によって異なります。おおよその目安：

• 1,000件: 約1分
• 10,000件: 約5-10分
• 100,000件: 約30-60分

Q: アプリケーション稼働中に移行を実行できますか？

競合状態を避けるため、メンテナンスウィンドウ中に移行を実行することをお勧めします。ゼロダウンタイムが必要な場合は、デュアルリードパターンを使用した段階的移行戦略を使用してください。

サポート

移行中に問題が発生した場合：

• GitHub Issues
• ドキュメント

関連ドキュメント

• 変更履歴 v1.1.0
• データ移行パターン
• テナントコード正規化移行