Follow up to #22642.

This reverts commit 4d06ea9a, reversing
changes made to e9d15072.

Reason: This will break oracle-enhanced, see
https://github.com/rsim/oracle-enhanced/blob/3c42131db82b64ac41645db3affc6e4650289df6/lib/active_record/connection_adapters/oracle_enhanced_adapter.rb#L1254

Even though this means more things to change when we bump after a
release, it's more important that our examples are directly copyable.

If we use a real version, at best that'll be an onerous update required
for each release; at worst, it will encourage users to write new
migrations against an older version than they're using.

The other option would be to leave these bare, without any version
specifier. But as that's just a variant spelling of "4.2", it would seem
to raise the same concerns as above.

The previous message was misleading (especially for Ops guys) when
diagnosing problems related to the database connection.

The message was suggesting that the connection cannot be obtained which
normally assumes the need to look at the database.

But this isn't the case as the connection could not be retrieved from
the application's internal connection pool.

The new message should make it more explicit and remove the confusion.

Reported on #21509, how views is treated by `#tables` are differ
by each adapters. To fix this different behavior, after Rails 5.0
is released, deprecate `#tables`.

And `#table_exists?` would check both tables and views.
To make their behavior consistent with `#tables`, after Rails 5.0
is released, deprecate `#table_exists?`.

The `native_database_types` only used in `TableDefinition` for look up
the default `:limit` option. But this is duplicated process with
`type_to_sql`. Passing `native_database_types` is not needed.

Columns are no longer stored in an attribute since b8a533d5.

[ci skip]

The getter is doing nothing more than returning the ivar, so it can be
extracted to an attr_reader.

[ci skip]

It's been a source of confusion that the lower-level `add_column`
referenced the higher level `column` method for available options.
`column` supports additional functionality like `index: true` that is
not present on `add_column`.

This patch moves common option documentation to `add_column` and only
documents the additional options in `column`.

Prior to this commit, Rails makes no differentiation between whether a
query uses bind parameters, and whether or not we cache that query as a
prepared statement. This leads to the cache populating extremely fast in
some cases, with the statements never being reused.

In particular, the two problematic cases are `where(foo: [1, 2, 3])` and
`where("foo = ?", 1)`. In both cases we'll end up quoting the values
rather than using a bind param, causing a cache entry for every value
ever used in that query.

It was noted that we can probably eventually change `where("foo = ?",
1)` to use a bind param, which would resolve that case. Additionally, on
PG we can change our generated query to be `WHERE foo = ANY($1)`, and
pass an array for the bind param. I hope to accomplish both in the
future.

For SQLite and MySQL, we still end up preparing the statements anyway,
we just don't cache it. The statement will be cleaned up after it is
executed. On postgres, we skip the prepare step entirely, as an API is
provided to execute with bind params without preparing the statement.

I'm not 100% happy on the way this ended up being structured. I was
hoping to use a decorator on the visitor, rather than mixing a module
into the object, but the way Arel has it's visitor pattern set up makes
it very difficult to extend without inheritance. I'd like to remove the
duplication from the various places that are extending it, but that'll
require a larger restructuring of that initialization logic. I'm going
to take another look at the structure of it soon.

This changes the signature of one of the adapter's internals, and will
require downstream changes from third party adapters. I'm not too
worried about this, as worst case they can simply add the parameter and
always ignore it, and just keep their previous behavior.

Fixes #21992.

The focus of this change is to make the API more accessible.
References to method and classes should be linked to make it easy to
navigate around.

This patch makes exzessiv use of `rdoc-ref:` to provide more readable
docs. This makes it possible to document `ActiveRecord::Base#save` even
though the method is within a separate module
`ActiveRecord::Persistence`. The goal here is to bring the API closer to
the actual code that you would write.

This commit only deals with Active Record. The other gems will be
updated accordingly but in different commits. The pass through Active
Record is not completely finished yet. A follow up commit will change
the spots I haven't yet had the time to update.

/cc @fxn

Closes #21563.

The `name` argument of `add_references` was both used to generate the
column name `<name>_id` and as the target table for the foreign key
`name.pluralize`.

It's primary purpose is to define the column name. In cases where the
`to_table` of the foreign key is different than the column name we
should be able to specify it individually.

Current master branch includes many schema dumping improvements.
It extract these features to the appropriate files.

These new methods are used from the Active Record model layer to
determine which relations are viable to back a model. These new methods
allow us to change `conn.tables` in the future to only return tables and
no views. Same for `conn.table_exists?`.

The goal is to provide the following introspection methods on the
connection:

* `tables`
* `table_exists?`
* `views`
* `view_exists?`
* `data_sources` (views + tables)
* `data_source_exists?` (views + tables)

Previously there was no separator between the two code examples so it looked like: 

```ruby
CREATE INDEX by_name ON accounts(name(10))
add_index(:accounts, [:name, :surname], name: 'by_name_surname', length: {name: 10, surname: 15})
```

If foreign keys specified in create table, generated SQL is slightly more
efficient.

Definition:

    ```
    create_table :testings do |t|
      t.references :testing_parent, foreign_key: true
    end
    ```

Before:

    ```
    CREATE TABLE "testings" ("id" serial primary key, "testing_parent_id" integer);
    ALTER TABLE "testings" ADD CONSTRAINT "fk_rails_a196c353b2" FOREIGN KEY ("testing_parent_id") REFERENCES "testing_parents" ("id");
    ```

After:

    ```
    CREATE TABLE "testings" ("id" serial primary key, "testing_parent_id" integer, CONSTRAINT "fk_rails_a196c353b2" FOREIGN KEY ("testing_parent_id") REFERENCES "testing_parents" ("id"));
    ```

Example:

    create_table :barcodes, primary_key: ["region", "code"] do |t|
      t.string :region
      t.integer :code
    end

The thread_safe gem is being deprecated and all its code has been merged
into the concurrent-ruby gem. The new class, Concurrent::Map, is exactly
the same as its predecessor except for fixes to two bugs discovered
during the merge.

[ci skip]

The **(11)** does not affect the storage size of the data type, which for an
INT will always be 4 bytes. It affects the **display width**.

http://www.tocker.ca/2015/07/02/proposal-to-deprecate-mysql-integer-display-width-and-zerofill.html

Follow up #21591.

The document of limit option for a text column is incorrect.

MySQL: the limit is byte length, not character length
Pg, Sqlite3: variable unlimited length

Follow up 7ba2cd06.

Bumps from `5.6` to `5.7`

It is always passed in

These 3 methods expect `ConnectionAdapters` to have `tables` method,
so make it clear that `tables` method is interface.

* `ConnectionAdapters::SchemaCache#prepare_tables`
* `db:schema:cache:dump` task
* `SchemaDumper#tables`

See http://www.postgresql.org/docs/9.4/static/sql-dropindex.html
for more details.