Motivation / Background

This Pull Request has been created because of a discussion we had in #53695

The reasoning for these new sections is:

• There no best practices written anywhere official regarding usage of select_all over exec_query over execute
• There is no documentation on how to use the binds argument of these methods. One would assume they support positional or named binds the same as where or any other method, however the reality is they do not. It only supports positional binds and they must be wrapped in an explicit array.
• Theres also a weird nil as the 2nd argument to all these methods prior to binds which makes it hard to understand how to properly use them
• It seems to be easier/better to use Arel.sql rather than attempt use the binds argument given the above

Below I show the current (poor) experience with binds on select_all (and other methods)

# Example 1
MyModel.connection.select_all("select title from posts where id = :id", nil, [1000])
# => Output SQL: "select title from post where id = 1000" 
# NOTE: it seems that the existing behaviour is quite bad as it somehow switches the named binds to positional ?

# Example 2
MyModel.connection.select_all("select title from posts where id = ?", nil, [1000])
# => Output SQL: "select title from post where id = 1000"

# Example 3
MyModel.connection.select_all("select title from posts where id = :id", nil, {id: 1000})
# => TypeError: can't cast Array (TypeError)

# Example 4
MyModel.connection.select_all("select title from posts where id = :id", nil, [[:id, 1000]])
# => TypeError: can't cast Array (TypeError)

Detail

This Pull Request adds a section to the documentation on the "Active Record Query Interface" page

The new sections are

Using Raw SQL
--> Sanitizing Raw SQL input
--> Executing model agnostic SQL queries for reads
--> Executing model agnostic SQL queries for writes

Additional information

After this documentation is merged. I would suggest that it might be wise to deprecate the binds argument from all these methods and instead recommend to use Arel.sql as a replacement. Suggested by @matthewd

Checklist

Before submitting the PR make sure the following are checked:

• This Pull Request is related to one change. Unrelated changes should be opened in separate PRs.
• Commit message has a detailed description of what changed and why. If this PR fixes a related issue include it in the commit message. Ex: [Fix #issue-number]
• Tests are added or updated if you fix a bug or add a feature.
• CHANGELOG files are updated for the changed libraries if there is a behavior change or additional feature. Minor bug fixes and documentation changes should not be included.