create-migration

Files (1)

• SKILL.md

SKILL.md (first lines)

# Create TiDB-Compatible Migration

TiDB互換のSQLxマイグレーションファイルを作成するスキル。

## TiDB DDL 重要制約

TiDBはMySQL互換だが、DDLに関して以下の重要な違いがある。**これらを理解せずにマイグレーションを書くとデプロイ時に失敗する。**

### 1. DDLは自動コミット（最重要）

TiDBではDDLステートメントは暗黙的にトランザクションをコミットする。**DDLとDMLを同一トランザクション/マイグレーションファイルに混在させてはならない。**

```sql
-- ❌ NG: DDL + DML を同じマイグレーションに書く
CREATE TABLE `new_table` (...);
INSERT INTO `new_table` VALUES (...);  -- DDLの自動コミット後に実行され、ロールバック不可

-- ❌ NG: ALTER TABLE 後に UPDATE
ALTER TABLE `users` ADD COLUMN `role` VARCHAR(20) DEFAULT 'user';
UPDATE `users` SET `role` = 'admin' WHERE `id` = 'us_xxx';  -- 同上

-- ✅ OK: DDLのみをマイグレーションに書く
ALTER TABLE `users` ADD COLUMN `role` VARCHAR(20) NOT NULL DEFAULT 'user';
-- データ投入はシードファイル（yaml-seeder）で行う
```

### 2. ADD COLUMNの制約

```sql
-- ✅ サポートされる
ALTER TABLE t ADD COLUMN col1 INT;
ALTER TABLE t ADD COLUMN IF NOT EXISTS col1 INT;
ALTER TABLE t ADD COLUMN col1 INT AFTER existing_col;
ALTER TABLE t ADD COLUMN col1 INT FIRST;
ALTER TABLE t ADD COLUMN col1 INT, ADD COLUMN col2 VARCHAR(50);  -- v6.2.0+

-- ❌ サポートされない
ALTER TABLE t ADD COLUMN col1 INT PRIMARY KEY;        -- 新カラムをPKに設定不可
ALTER TABLE t ADD COLUMN col1 INT AUTO_INCREMENT;     -- 新カラムをAUTO_INCREMENTに設定不可

-- ❌ 同じALTER内で新カラムをAFTERで参照不可
ALTER TABLE t ADD COLUMN c1 INT, ADD COLUMN c2 INT AFTER c1;  -- c1はまだ存在しないためエラー
-- ✅ 別のALTER文に分ける
ALTER TABLE t ADD COLUMN c1 INT;
ALTER TABLE t ADD COLUMN c2 INT AFTER c1;
```

### 3. Multi-Schema Change（v6.2.0+）

単一のALTER TABLEで複数の操作が可能。ただし**同じオブジェクトを複数回変更することは不可**。

```sql
-- ✅ OK: 異なるカラムを同時に操作
ALTER TABLE `t`
  ADD COLUMN `a` INT,
  ADD COLUMN `b` VARCHAR(50),
  DROP COLUMN `c`;

-- ❌ NG: 同じカラムを複数回変更
ALTER TABLE `t`
  ADD COLUMN `a` INT,
  MODIFY COLUMN `a` BIGINT;  -- 同じカラム `a` を2回変更
```

### 4. DROP COLUMNの制約

```sql
-- ✅ サポートされる
ALTER TABLE t DROP COLUMN col1;
ALTER TABLE t DROP COLUMN IF EXISTS col1;

-- ❌ サポートされない
-- PKカラムのDROPは不可
-- 複合インデックスに含まれるカラムのDROPは不可（インデックスを先に削除する）
-- ビューやエクスプレッションインデックスから参照されているカラムのDROPは不可

-- ❌ 複数カラムの同時DROPは不可
ALTER TABLE t DROP COLUMN col1, DROP COLUMN col2;  -- エラー: can't run multi schema change
-- ✅ 別々のALTER文に分ける
ALTER TABLE t DROP COLUMN col1;
ALTER TABLE t DROP COLUMN col2;
```

### 5. MODIFY COLUMN の制約

```sql
-- ✅ サポートされる: 型の拡大（INT→BIGINT）、NULLable化、デフォルト値変更、COMMENT変更
ALTER TABLE t MODIFY COLUMN col1 BIGINT;
ALTER TABLE t MODIFY COLUMN col1 VARCHAR(100) NULL;

-- ⚠️ 制限付き: 型変更はLossy Column Type Change（データロスの可能性）
--   INTEGER型同士の変更は可能（INT→BIGINT等）
--   VARCHAR長の拡大は可能
--   VARCHAR→TEXT等の互換性のない変更は要注意
```

### 6. ADD INDEX のパフォーマンス影響

ADD INDEXはオンライン操作だが、**書き込み負荷の高い本番環境では性能に影響する**。

- 状態遷移: `absent → delete only → write only → write reorg → public`
- `write reorg`フェーズでバックフィルが発生し、TiKVのCPU/IOを消費
- 書き込みが多いカラムへのインデックス追加はTPSが大幅に低下する可能性あり

**本番での対策:**
```sql
-- インデックス作成の並列度を下げる（デフォルトの1/8）
SET @@global.tidb_ddl_reorg_worker_cnt = 4;
SET @@global.tidb_ddl_reorg_batch_size = 256;
```

### 7. テーブル置き換えパターン（大規模スキーマ変更）

PKの変更やカラム位置の大幅変更には「テーブル置き換え」パターンを使用する。

```sql
-- 1. 新テーブル作成
CREATE TABLE `users__new` (
    `id` VARCHAR(29) NOT NULL,

From quantum-box/tachyon-skills, MIT.

More from quantum-box/tachyon-skills