Part of a larger refactoring to remove type casting from Arel.

/cc @mrgilman

[Sean Griffin & Melanie Gilman]

A custom object is required for this, as you cannot build a range
object out of `Arel::Nodes::Quoted` objects. Depends on the changes
introduced in
https://github.com/rails/arel/commit/cf03bd45e39def057a2f63e42a3391b7d750dece

/cc @mrgilman

As part of the larger refactoring to remove type casting from Arel, we
need to do the casting of values eagerly. The predicate builder is the
closest place that knows about the Active Record class, and can
therefore have the type information.

/cc @mrgilman

[Sean Griffin & Melanie Gilman]

This class cares far too much about the internals of other parts of
Active Record. This is an attempt to break out a meaningful object which
represents the needs of the predicate builder. I'm not fully satisfied
with the name, but the general concept is an object which represents a
table, the associations to/from that table, and the types associated
with it. Many of these exist at the `ActiveRecord::Base` class level,
not as properties of the table itself, hence the need for another
object. Currently it provides these by holding a reference to the class,
but that will likely change in the future. This allows the predicate
builder to remain wholy concerned with building predicates.

/cc @mrgilman

I'm attempting to remove `klass` as a dependency of the predicate
builder, in favor of an object that better represents what we're using
it for. The only part of this which doesn't fit nicely into that picture
is the check for an association being polymorphic. Since I'm not yet
sure what that is going to look like, I've moved this logic into another
class in an attempt to separate things that will change from things that
won't.

This reduces the number of places which will need to care about single
value or range specific logic as we introduce type casting. The array
handler is only responsible for producing `in` statements.

/cc @mrgilman

[Sean Griffin & Melanie Gilman]

This will allow us to pass the predicate builder into the constructor of
these handlers. The procs had to be changed to objects, because the
`PredicateBuilder` needs to be marshalable. If we ever decide to make
`register_handler` part of the public API, we should come up with a
better solution which allows procs.

/cc @mrgilman

[Sean Griffin & Melanie Gilman]

We're accidentally documenting `PredicateBuilder` and `ArrayHandler`
since there's a constant which is missing `# :nodoc:`

Construction of relations can be a hotspot, we don't want to create one
of these in the constructor. This also allows us to do more expensive
things in the predicate builder's constructor, since it's created once
per AR::Base subclass

We don't memoize the relation instance

I think we should deprecate this behavior and just error if you tell us
to do a case insensitive comparison for types which are not case
sensitive. Partially reverts 35592307

Fixes #18195

`Rails` constant is added by rails-html-sanitizer leading to bugs in
non-Rails apps using ActiveRecord and ActionMailer

Clarify that query methods have a custom definition of whether a numeric value is present. [ci skip]

The way Active Record query methods handle numeric values is a special case, and is not part of Rails's standard definition of present. This update attempts to make this more clear in the docs, so that people don't expect Object#present? to return false if used on a number that is zero.

All cases are properly handled in CollectionAssociation
for all subclasses of this association

We were ignoring the `default_value?` escape clause in the serialized
type, which caused the default value to always be treated as changed.

Fixes #18169

The code for `TableDefinition#references` and
`SchemaStatements#add_reference` were almost identical both
structurally, and in terms of domain knowledge. This removes that
duplication into a common class, using the `Table` API as the expected
interface of its collaborator.

This isn't Seattle.rb, @senny. ;)

The code in `ConnectionPool#release` assumed that a single thread only
ever holds a single connection, and thus that releasing a connection
only requires the owning thread_id.

There is a trivial counterexample to this assumption: code that checks
out additional connections from the pool in the same thread. For
instance:

    connection_1 = ActiveRecord::Base.connection
    connection_2 = ActiveRecord::Base.connection_pool.checkout
    ActiveRecord::Base.connection_pool.checkin(connection_2)
    connection_3 = ActiveRecord::Base.connection

At this point, connection_1 has been removed from the
`@reserved_connections` hash, causing a NEW connection to be returned as
connection_3 and the loss of any tracking info on connection_1. As long
as the thread in this example lives, connection_1 will be inaccessible
and un-reapable. If this block of code runs more times than the size of
the connection pool in a single thread, every subsequent connection
attempt will timeout, as all of the available connections have been
leaked.

Reverts parts of 9e457a86 and
essentially all of 4367d2f0

I just wasted an absurd amount of time trying to figure out why my model
wasn't being deleted even though I was setting `_destroy` to true like
the instructions said. Making the documentation a little bit clear so
that someone like me doesn't waste their time in future.

Update Active Record's attribute query methods documentation to clarify that whether an attribute is present is based on Object#present?. This gives people a place to go see what the exact definition of presence is. [ci skip]

This bug occurs when an attribute of an ActiveRecord model is an
ActiveRecord::Type::Integer type or a ActiveRecord::Type::Decimal type (or any
other type that includes the ActiveRecord::Type::Numeric module. When the value
of the attribute is negative and is set to the same negative value, it is marked
as changed.

Take the following example of a Person model with the integer attribute age:

    class Person < ActiveRecord::Base
      # age          :integer(4)
    end

The following will produce the error:

    person = Person.new(age: -1)
    person.age = -1
    person.changes
    => { "age" => [-1, -1] }
    person.age_changed?
    => true

The problematic line is here:

    module ActiveRecord
      module Type
        module Numeric
          ...

          def non_numeric_string?(value)
            # 'wibble'.to_i will give zero, we want to make sure
            # that we aren't marking int zero to string zero as
            # changed.
            value.to_s !~ /\A\d+\.?\d*\z/
          end
        end
      end
    end

The regex match doesn't accept numbers with a leading '-'.

Update Active Record's attribute query methods documentation to describe its full behaviour. [ci skip]

`ActiveRecord::Base#[]` has overhead that was introduced in 4.2. The
`foo["id"]` working with PKs other than ID isn't really a case that we
want to support publicly, but deprecating was painful enough that we
avoid it. `_read_attribute` was introduced as the faster alternative for
use internally. By using that, we can save a lot of overhead. We also
save some overhead by reading the attribute one fewer times in
`stale_state`.

Fixes #18151

If there is a method defined such as `find_and_do_stuff(id)`, which then
gets called on an association, we will perform statement caching and the
parent ID will not change on subsequent calls.

Fixes #18117

Calling `changed_attributes` will ultimately check if every mutable
attribute has changed in place. Since this gets called whenever an
attribute is assigned, it's extremely slow. Instead, we can avoid this
calculation until we actually need it.

Fixes #18029

This has the same comments as 9af90ffa00ba35bdee888e3e1ab775ba0bdbe72c,
however it affects the `add_reference` method, and `t.references` in the
context of a `change_table` block.

There is a lot of duplication of code between creating and updating
tables. We should re-evaluate the structure of this code from a high
level so changes like this don't need to be made in two places. (Note to
self)

While we still aren't accepting PRs that only make changes like this,
it's fine when we're actively working on a method if it makes our lives
easier.

Rather than having to do:

    create_table :posts do |t|
      t.references :user
    end

    add_foreign_key :posts, :users

You can instead do:

    create_table :posts do |t|
      t.references :user, foreign_key: true
    end

Similar to the `index` option, you can also pass a hash. This will be
passed as the options to `add_foreign_key`. e.g.:

    create_table :posts do |t|
      t.references :user, foreign_key: { primary_key: :other_id }
    end

is equivalent to

    create_table :posts do |t|
      t.references :user
    end

    add_foreign_key :posts, :users, primary_key: :other_id

While we aren't taking PRs with these kinds of changes just yet, they
are fine if we're actively working on the method and it makes things
easier.

PG doesn't register it's types using the `int(4)` format that others do.
As such, if we alias `int8` to the other integer types, the range
information is lost. This is fixed by simply registering it separately.

The other option (which I specifically chose to avoid) is to pass the
information of the original type that was being aliased as an argument.
I'd rather avoid that, since an alias should truly be treated the same.
If we need different behavior for a different type, we should explicitly
register it with that, and not have a conditional based on aliasing.

Fixes #18144

[Sean Griffin & ysbaddaden]

Fixes #18122

Add nodoc to some constants [skip ci]