JSONB カラムの内部型を変えたら既存データのエンコード形を backfill する
ORM
データベース
設計判断
データマイグレーション
知識
運用
ORM model で JSONB カラムを汎用文字列として扱っていた実装から、配列や構造体などの厳格な内部型へ変える場合、コードだけを直しても既存データが読めなくなることがある。旧実装が配列を JSON 文字列として二重エンコードして保存していると、新実装の scan は「配列を期待したのに文字列が来た」状態になり、一覧取得や更新がサーバーエラーになる。
判断基準
- JSONB カラムの Go/TypeScript/ORM 側の型を
stringから[]Tや struct slice に変えるときは、既存 row の JSON 型も確認する。 - DB カラム型が
jsonbであっても、中身が array とは限らない。DB 側で JSON 型を確認し、array / object / string / null が想定と一致するか見る。 - 既存 row が JSON 文字列として保存されている場合は、コードデプロイだけでなく、JSON 文字列を取り出して JSON として戻す backfill が必要になる。
- その JSON に project や tenant などの文脈補完済みデータが含まれる場合、単純変換だけで正しいとは限らない。旧ソースや監査ログと照合して、補完バグで混入した値があれば同時に戻す。
検証
補正前に本文や機密値を出さず、対象カラムの JSON 型と件数を確認する。補正後は DB 側で対象カラムが期待する JSON 型に揃ったことを確認し、さらにアプリ/API 経由で一覧取得・更新対象の読み込みが成功することを確認する。