skip]

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.

This can resolve confusing situation when a top level constant exists
but a namespaced version is identified.

Related to #19531.

Add full set of MySQL CLI options to support SSL authentication when using db:structure dump and load

fix minor problems

This method has already been removed.

Stems from https://github.com/rails/rails/pull/20105#issuecomment-100900939
where @senny said:

> From my point of view, all the docs (guides, API) are version bound.
> They should describe that version and continue to be available when newer versions are released.
> The cross referencing can be done by the interested user.

If your STI class looks like this:

```ruby
class Company < ActiveRecord::Base
  self.store_full_sti_class = false

  class GoodCo < Company
  end

  class BadCo < Company
  end
end
```

The expectation (which is valid) is that the `type` in the database is saved as
`GoodCo` or `BadCo`. However, another expectation should be that setting `type`
to `GoodCo` would correctly instantiate the object as a `Company::GoodCo`. That
second expectation is what this should fix.

Now that master points at Rails 5, we might not need to explain how
things used to work in Rails 3. Or we might… up to you 😁

the module name was changed in 8e814a0a

Its already doc'ed in
activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb

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

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

MySQL does not support partial index. And, the create index algorithm in
create table can not be specified.

Example:

    create_table :foos do |t|
      t.string :string_en, collation: 'en_US.UTF-8'
      t.text   :text_ja,   collation: 'ja_JP.UTF-8'
    end

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

Follow up #18914.

If the adapter supports indexes in create table, generated SQL is
slightly more efficient.

Its nodoc'ed for the other implementations, and doc'ed in the base
class, just like the other change_column* methods.

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

`change_column_null` is doc'ed only in
ActiveRecord::ConnectionAdapters::SchemaStatements, so it would make
sense to :nodoc: it elsewhere.