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 経由で一覧取得・更新対象の読み込みが成功することを確認する。