PostgreSQL設定の`schema_order`オプションを非推奨化

2026年03月28日 05:35 JST rails/rails

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

RailsのPostgreSQLアダプターにおいて、旧来のエイリアスである schema_order オプションが非推奨となりました。Rails 8.3での削除に向け、schema_search_path への移行が求められます。

背景

schema_order は schema_search_path が現在の名称として定まる以前から存在していた旧来のエイリアスです。PostgreSQLのスキーマ検索パスを指定するという機能は同一ながら、オプション名の乖離が続いていました。今回の変更は、この命名の不整合を解消し、設定キーを一本化するために行われています。

これまで postgresql_adapter.rb のドキュメントコメントでは schema_search_path の説明に「schema_order オプションとの後方互換性あり」と明記されていましたが、今回の非推奨化に伴いその記述は削除されています。

技術的な変更

非推奨警告は configure_connection メソッド内で、スキーマ検索パスを設定するロジックの直前に追加されました。

変更前:

unless @config[:schema_search_path] == false
  self.schema_search_path = @config[:schema_search_path] || @config[:schema_order]
end

変更後:

unless @config[:schema_search_path] == false
  if @config[:schema_order]
    ActiveRecord.deprecator.warn(<<~MSG.squish)
      The `schema_order` option in PostgreSQL database configurations is
      deprecated and will be removed in Rails 8.3. Use `schema_search_path` instead.
    MSG
  end
  self.schema_search_path = @config[:schema_search_path] || @config[:schema_order]
end

schema_order を設定している場合に ActiveRecord.deprecator 経由で警告を発するという構造で、警告発行後も @config[:schema_order] は引き続きフォールバックとして参照されます。これにより、Rails 8.3の削除までは実際の動作に変化はなく、移行猶予が与えられています。

テストコードでは、schema_order: "public" を渡して接続した際に非推奨警告が発生し、かつ schema_search_path が正しく "public" に設定されることを assert_deprecated と assert_equal で検証しています。

設計判断

ActiveRecord.deprecator を経由した警告方式は、Railsが標準的に採用している非推奨化パターンです。ActiveSupport::Deprecation の仕組みを利用することで、アプリケーション側での警告の抑制・集約・カスタマイズが可能になります。

機能を即座に削除するのではなく、警告を挟む移行期間を設けることで、既存の設定ファイルを持つアプリケーションへの影響を最小化しています。schema_search_path と schema_order が両方指定された場合は schema_search_path が優先される既存の || による評価順序も維持されています。

まとめ

この変更は機能追加ではなく、命名の統一に向けた整理です。database.yml などで schema_order を使用しているプロジェクトは、Rails 8.3の削除前に schema_search_path へのキーの置き換えを行うことで、将来の破壊的変更を回避できます。