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

This reverts commit 1502caef.

The test suite for the mysql adapter broke when this commit was used
with MySQL 5.6.

Conflicts:
	activerecord/CHANGELOG.md

MySQL rejects to remove an index which is used in a foreign key constraint:

```
ActiveRecord::StatementInvalid: Mysql2::Error: Cannot drop index 'index_copies_on_title_id': needed in a foreign key constraint: ALTER TABLE `copies` DROP `title_id`
```

Removing the constraint before removing the column (and the index) solves this problem.

If set to `if_exists: true`, it generates a statement like:

    DROP TABLE IF EXISTS posts

This syntax is supported in the popular SQL servers, that is (at least)
SQLite, PostgreSQL, MySQL, Oracle and MS SQL Sever.

Closes #16366.

In most cases, `create_table_definition` called by table_name (the first
argument) only.

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 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

When running the following migration:

    change_table(:table_name) { |t| t/timestamps }

The following error was produced:

    wrong number of arguments (2 for 1) .... /connection_adapters/abstract/schema_statements.rb:851:in `remove_timestamps'

This is due to `arguments` containing an empty hash as its second
argument.

This makes the following changes:
  * warn if `:null` is not passed to `add_timestamps`
  * `timestamps` method docs link to `add_timestamps` docs
  * explain where additional options go
  * adjust examples to include `null: false` (to prevent deprecation warnings)

`add_reference` can very helpfully add a multi-column index when you use
it to add a polymorphic reference. However, the first column in the
index is the `id` column, which is less than ideal.

The [PostgreSQL docs][1] say:
> A multicolumn B-tree index can be used with query conditions that
> involve any subset of the index's columns, but the index is most
> efficient when there are constraints on the leading (leftmost)
> columns.

The [MySQL docs][2] say:
> MySQL can use multiple-column indexes for queries that test all the
> columns in the index, or queries that test just the first column, the
> first two columns, the first three columns, and so on. If you specify
> the columns in the right order in the index definition, a single
> composite index can speed up several kinds of queries on the same
> table.

In a polymorphic relationship, the type column is much more likely to be
useful as the first column in an index than the id column. That is, I'm
more likely to query on type without an id than I am to query on id
without a type.

[1]: http://www.postgresql.org/docs/9.3/static/indexes-multicolumn.html
[2]: http://dev.mysql.com/doc/refman/5.0/en/multiple-column-indexes.html

[Yves Senn & Matthew Draper]

The column check was embodied in the defaul index name.
If the :name option was used, the specified columns were not verified at all.

Given:

```
assert connection.index_exists?(table_name, :foo_id, :name => :index_testings_on_yo_momma)
```

That index could have been defined on any field, not necessarily on `:foo_id`.

As per discussion, this changes the model generators to specify
`null: false` for timestamp columns. A warning is now emitted if
`timestamps` is called without a `null` option specified, so we can
safely change the behavior when no option is specified in Rails 5.

[Andrey Novikov & Łukasz Sarnacki]

The name of the foreign key is not relevant from a users perspective.
Using random names resolves the urge to rename the foreign key when the
respective table or column is renamed.

This allows to create and remove foreign keys without specifying a column.