Merge pull request rails#42963 from jordannb/fix-unknown-attr-ref-err-doc

API Docs: Use Arel.sql examples that require Arel.sql

Author: kamipo

activerecord/lib/active_record/errors.rb

@@ -470,12 +470,12 @@ class AdapterTimeout < QueryAborted
   #
   # For example, the following code would raise this exception:
   #
-  #   Post.order("length(title)").first
+  #   Post.order("REPLACE(title, 'misc', 'zzzz') asc").pluck(:id)
   #
   # The desired result can be accomplished by wrapping the known-safe string
   # in Arel.sql:
   #
-  #   Post.order(Arel.sql("length(title)")).first
+  #   Post.order(Arel.sql("REPLACE(title, 'misc', 'zzzz') asc")).pluck(:id)
   #
   # Again, such a workaround should *not* be used when passing user-provided
   # values, such as request parameters or model attributes to query methods.

activerecord/lib/arel.rb

@@ -29,7 +29,7 @@ module Arel
 
   # Wrap a known-safe SQL string for passing to query methods, e.g.
   #
-  #   Post.order(Arel.sql("length(title)")).last
+  #   Post.order(Arel.sql("REPLACE(title, 'misc', 'zzzz') asc")).pluck(:id)
   #
   # Great caution should be taken to avoid SQL injection vulnerabilities.
   # This method should not be used with unsafe values such as request