This commit fixes the generated HTML of the two code examples.

invalid column type
    /activerecord/lib/active_record/connection_adapters
    /abstract/schema_definitions.rb:306
    type = type.to_sym

Changed to the following to handle nil case:
    type = type.to_sym if type

Added regression test for this case:
  /activerecord/test/cases/migration_test.rb:554
  if current_adapter?(:SQLite3Adapter)
    def test_allows_sqlite3_rollback_on_invalid_column_type
      Person.connection.create_table :something, force: true do |t|
        t.column :number, :integer
        t.column :name, :string
        t.column :foo, :bar
      end
      assert Person.connection.column_exists?(:something, :foo)
      assert_nothing_raised { Person.connection.remove_column :something, :foo, :bar }
      assert !Person.connection.column_exists?(:something, :foo)
      assert Person.connection.column_exists?(:something, :name)
      assert Person.connection.column_exists?(:something, :number)
    ensure
      Person.connection.drop_table :something, if_exists: true
    end
  end

Unfortunately `t.timestamps` in `create_table` allows unused splat args.
But the same one in `change_table` does not allow them.
This commit fixes the inconsistent behavior.

The current code base is not uniform. After some discussion,
we have chosen to go with double quotes by default.

Currently CI is broken due to 56a61e0c and c4cb6862. This occurred because
the failures are not present on SQLite which is what I normally run
locally before pushing.

The optimizations to our YAML size were dropping mutations, as
`with_type` didn't set the previous value if it'd already been read
(that method was never really designed to be used with values on
individual objects, it was previously only used for defaults). I'm
questioning whether there's a better place to be handling the exclusion
of the type, but this will fix the failing build.

Additionally, there was a bug in `remove_foreign_key` if you passed it
an options hash containing `to_table`. This now occurs whenever removing
a reference, as we always normalize to a hash.

[Sean Griffin & Ryuta Kamizono]

* Switch to keyword args where we can without breaking compat.
* Use add_table_options! for :options, too.
* Some code polish.

Comments are specified in migrations, stored in database itself (in its schema),
and dumped into db/schema.rb file.

This allows to generate good documentation and explain columns and tables' purpose
to everyone from new developers to database administrators.

For PostgreSQL and MySQL only. SQLite does not support comments at the moment.

See docs for PostgreSQL: http://www.postgresql.org/docs/current/static/sql-comment.html
See docs for MySQL: http://dev.mysql.com/doc/refman/5.7/en/create-table.html

Previously if you used `t.foreign_key` twice within the same
`create_table` block using the same `to_table`, all statements except
the final one would fail silently. For example, the following code:

    def change
      create_table :flights do |t|
        t.integer :from_id, index: true, null: false
        t.integer :to_id,   index: true, null: false

        t.foreign_key :airports, column: :from_id
        t.foreign_key :airports, column: :to_id
      end
    end

Would only create one foreign key, on the column `from_id`.

This commit allows multiple foreign keys to the same table to be created
within one `create_table` block.

With this addition, you can add a column into the table like:

```
  create_table(:numeric_types) do |t|
    t.numeric :foo, precision: 10, scale: 2, default: 2.0
  end
```

The result of the migration above is same with:

```
  create_table(:numeric_types) do |t|
    t.decimal :foo, precision: 10, scale: 2, default: 2.0
  end
```

- Using `references` or `belongs_to` in migrations will always add index
  for the referenced column by default, without adding `index:true` option
  to generated migration file.
- Users can opt out of this by passing `index: false`.
- Legacy migrations won't be affected by this change. They will continue
  to run as they were before.
- Fixes #18146

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

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.

Example:

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

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

Passing `:from` and `:to` to `change_column_default` makes this command
reversible as user has defined its previous state.

So, instead of having the migration command as:

    change_column_default(:posts, :state, "draft")

They can write it as:

    change_column_default(:posts, :state, from: nil, to: "draft")

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.

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

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.

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

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