`insert_all` / `upsert_all` のキー不一致エラーに差分情報を追加

2026年05月23日 06:39 JST rails/rails

https://github.com/rails/rails/pull/57447

insert_all / upsert_all でキー不一致が発生した際のエラーメッセージに、どのキーが不足・余剰なのかを示す情報が付加されるようになりました。デバッグ時に全ハッシュを目視確認する手間を省けます。

背景

これまでのエラーメッセージは問題の存在を伝えるのみで、原因の特定には役立ちませんでした。insert_all / upsert_all は、渡されたオブジェクト群のキーが一致しない場合に ArgumentError を送出しますが、そのメッセージは "All objects being inserted must have the same keys" という固定文字列でした。

カラム数の多いテーブルや大きなバッチを扱う場合、どのキーが原因なのかを特定するには全ハッシュを目視で照合する必要がありました。この「エラーは出るが手がかりがない」状態がデバッグコストを高めていました。

不一致のあるキーをエラーメッセージに含めることで、原因箇所を即座に特定できるようになります。

技術的な変更

変更は activerecord/lib/active_record/insert_all.rb の verify_attributes メソッドに集約されており、差分計算とメッセージ生成のロジックが数行で追加されています。

変更前:

def verify_attributes(attributes)
  if keys_including_timestamps != attributes.keys.sort!
    raise ArgumentError, "All objects being inserted must have the same keys"
  end
end

変更後:

def verify_attributes(attributes)
  if keys_including_timestamps != attributes.keys.sort!
    missing = keys_including_timestamps - attributes.keys
    extra = attributes.keys - keys_including_timestamps
    details = []
    details << "missing: #{missing.inspect}" if missing.any?
    details << "extra: #{extra.inspect}" if extra.any?
    raise ArgumentError, "All objects being inserted must have the same keys (#{details.join(", ")})"
  end
end

missing と extra はそれぞれ「基準キー集合に存在するが対象ハッシュにない」「対象ハッシュにあるが基準キー集合にない」を表し、配列差分演算子 - で求めます。details 配列に any? で条件付きで追記し、join で結合することで、片方のみ・両方のケースいずれも自然に処理されます。

差分計算はエラーが発生する場合にのみ実行されるため、正常系のパスで余分なアロケーションは発生しません。新規メソッドの追加もなく、既存のインターフェースも変わらないため、既存コードへの影響はゼロです。

出力例を以下に示します：

余剰キーがある場合: ArgumentError: All objects being inserted must have the same keys (extra: [:isbn])
不足キーがある場合: ArgumentError: All objects being inserted must have the same keys (missing: [:isbn])

設計判断

エラー発生時のみ差分を計算するインライン実装が選ばれました。

PR内では「ヘルパーメソッドを追加しない」「ハッピーパスにコストをかけない」という方針が明示されています。差分計算を verify_attributes の条件分岐内にインライン展開することで、正常系の実行パスにはいかなるオーバーヘッドも生じません。また、既存のテストがエラーメッセージの固定文字列を assert_equal ではなく正規表現で検証していないことを grep で確認した上で変更しており、後方互換性を壊さない配慮がされています。

新たなテストは assert_match を使って extra と missing の両パスを独立して検証しており、メッセージ全体への厳密な文字列一致を避けることで将来の文言変更に対しても堅牢な設計になっています。

まとめ

この変更は、エラーメッセージという「既存インターフェースの改善」に絞った最小限の修正です。差分計算をエラーパスのみに閉じ込め、正常系のコストを一切増やさない設計は、デバッグ体験とパフォーマンスを同時に両立させた実用的なアプローチといえます。