This patch
  - reduces the duplication among the `reference`-family methods.
  - better explains all the optians available for `add_reference`.
  - redirects to user from `references` to `add_reference`.

Originated by #20184.

Active Record detects when the process has forked and automatically
creates a new connection pool to avoid sharing file descriptors.

If the existing connection pool had a schema cache associated with it,
the new pool should copy it to avoid unnecessarily querying the database
for its schema.

The code to detect that the process has forked is in ConnectionHandler,
but the existing test for it was in the ConnectionManagement test file.
I moved it to the right place while I was writing the new test for this
change.

Renamed `@reserved_connections` -> `@thread_cached_conns`. New name
clearly conveys the purpose of the cache, which is to speed-up
`#connection` method.

The new `@thread_cached_conns` now also uses `Thread` objects as keys
(instead of previously `Thread.current.object_id`).

Since there is no longer any synchronization around
`@thread_cached_conns`, `disconnect!` and `clear_reloadable_connections!`
methods now pre-emptively obtain ownership (via `checkout`) of all
existing connections, before modifying internal data structures.

A private method `release` has been renamed `thread_conn_uncache` to
clear-up its purpose.

Fixed some brittle `thread.status == "sleep"` tests (threads can go
into sleep even without locks).

Move post checkout connection verification out of mutex.synchronize.

`select_one` create `ActiveRecord::Result` instance. It is better to use
`select_rows` instead of `select_one` for performance.

Some databases like MySQL allow defining collation charset for specific
columns.

The microseconds handling was already moved to `Quoting#quoted_date`.

 - This method is used only by adapters to validate length of new index names.

 - Added documentation for index_name_exists? and rename_index.
 - Also changed rails to \Rails in documentation of
   allowed_index_name_length.

The `db:schema:cache:dump` rake task dumps the database schema structure
to `db/schema_cache.dump`. If this file is present, the schema details
are loaded into the currently checked out connection by a railtie while
Rails is booting, to avoid having to query the database for its schema.

The schema cache dump is only applied to the initial connection used to
boot the application though; other connections from the same pool are
created with an empty schema cache, and still have to load the structure
of each table directly from the database.

With this change, a copy of the schema cache is associated with the
connection pool and applied to connections as they are created.

follow up to 107526e8

The `index` option used with `timestamps` should be passed to both
`column` definitions for `created_at` and `updated_at` rather than just
the first.

This was happening because `Hash#delete` is used to extract the `index`
option passed to `timestamps`, thereby mutating the `options` hash
in-place. Now take a copy of the `options` before deleting so that the
original is not modified.

Fixes #18106

We should document current behavior, and this is design of API for now.

Closes #17597

The implementation of the generation of the foreign key name was changed
between Rails 4.2.0 and 4.2.1 from a random to a deterministic behavior,
however the documentation still describes the old randomized behavior.

It behaves in the same way that the abstract adapter.

[ci skip]

test case for use singular table name if pluralize_table_names is setted as false while creating foreign key

refactor references foreign key addition tests

use singular table name while removing foreign key

merge foreign key singular table name methods

remove unnecessary drop table from test

https://github.com/ruby/ruby/pull/579 - there is a new optimization
since ruby 2.2

Previously regexp patterns were faster (since a string was converted to
regexp underneath anyway). But now string patterns are faster and
better reflect the purpose.

  Benchmark.ips do |bm|
    bm.report('regexp') { 'this is ::a random string'.gsub(/::/, '/') }
    bm.report('string') { 'this is ::a random string'.gsub('::', '/') }
    bm.compare!
  end
  # string: 753724.4 i/s
  # regexp: 501443.1 i/s - 1.50x slower

This reverts commit 796cab45.

- Add example to column_exists?
- Add example to index_exists?
- Add document for foreign_key
- Add document for foreign_key_exists?

This reverts commit a38732c8.

Since the mutation logic was reverted in
07278519, we must bring the reader
method back as well, since the implementation relies on it.

This reverts commit 393e65b4 and
ec51c3fe

We don't want the records to hold hard references to transactions
because they point at records that have callbacks.

this lets us keep singleton instances of "state" values and precalculate
return values of things like `finalized?` and `completed?`.

this way we don't have to mutate a state object, we can just change the
state of the txn