- So that we can just copy paste the command and execute it

Still more to do. Please assist!

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.

- key was a poor choice of name. A key implies something that will
  unlock a lock. The concept is actually more like a 'lock identifier'
- mysql documentation calls this a 'lock name'
- postgres documentation calls it a 'lock_id'
- Updated variable names to reflect the preferred terminology for the database in
  question

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

`1_valid_people_have_last_names.rb` and
`20150823202140_create_users.rb` are valid migration file name.
But `1_valid_people_have_last_names.rb` is rendered as
`********** NO FILE **********` when `rake db:migrate:status`.

Fix to this bug, this commit includes

* define some API private methdos and a Constant
  `match_to_migration_filename?`, `parse_migration_filename`, and
  `MigrationFilenameRegexp`
* use these methods in `db:migrate:status` task

Example:

These files are in `db/migrate`

* 1_valid_people_have_last_names.rb
* 20150819202140_irreversible_migration.rb
* 20150823202140_add_admin_flag_to_users.rb
* 20150823202141_migration_tests.rb
* 2_we_need_reminders.rb
* 3_innocent_jointable.rb

we can migrate all of them.

Before

```shell
$ bundle exec rake db:migrate:status

...

 Status   Migration ID    Migration Name
--------------------------------------------------
   up     001             ********** NO FILE **********
   up     002             ********** NO FILE **********
   up     003             ********** NO FILE **********
   up     20150819202140  Irreversible migration
   up     20150823202140  Add admin flag to users
   up     20150823202141  Migration tests
```

After

```shell
$ bundle exec rake db:migrate:status

...

 Status   Migration ID    Migration Name
--------------------------------------------------
   up     001             Valid people have last names
   up     002             We need reminders
   up     003             Innocent jointable
   up     20150819202140  Irreversible migration
   up     20150823202140  Add admin flag to users
   up     20150823202141  Migration tests
```

- Addresses issue #22092
- Works on Postgres and MySQL
- Uses advisory locks because of two important properties:
  1. The can be obtained outside of the context of a transaction
  2. They are automatically released when the session ends, so if a
  migration process crashed for whatever reason the lock is not left
  open perpetually
- Adds get_advisory_lock and release_advisory_lock methods to database
  adapters
- Attempting to run a migration while another one is in process will
  raise a ConcurrentMigrationError instead of attempting to run in
  parallel with undefined behavior. This could be rescued and
  the migration could exit cleanly instead. Perhaps as a configuration
  option?

Technical Notes
==============

The Migrator uses generate_migrator_advisory_lock_key to build the key
for the lock. In order to be compatible across multiple adapters there
are some constraints on this key.
- Postgres limits us to 64 bit signed integers
- MySQL advisory locks are server-wide so we have to scope to the
  database
- To fulfil these requirements we use a Migrator salt (a randomly
  chosen signed integer with max length of 31 bits) that identifies
  the Rails migration process as the owner of the lock. We multiply
  this salt with a CRC32 unsigned integer hash of the database name to
  get a signed 64 bit integer that can also be converted to a string
  to act as a lock key in MySQL databases.
- It is important for subsequent versions of the Migrator to use the
  same salt, otherwise different versions of the Migrator will not see
  each other's locks.

`alias :migrations_path= :migrations_paths=`, so
`migrations_path = some_string` is correct.

The last call site of `last_version` was removed with:

838e1832

This method is private API and never used. Let's remove it.

This change allows to instantiate all ActiveRecordError descendant
execption classes without arguments, which might be useful in testing
and is far less surprising than mandatory arguments.

In rails generally migration file's timestamp is "YYYYMMDDHHMMSS".

`ActiveRecord::Migration` has `connetion` method so replace to use
`connection` method to get `@connection` as much as possible

[ci skip]

fix tests

[ci skip]

`remove_index` works with multiple column names as `add_index`

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.

I think this was supposed to be "roundTrip".

This constant may be define for auxiliar gems like rails-html-sanitizer
and these methods call will fail.

This reverts deprecations added in #13528.
The task is brought back for two reasons:
  1. Give plugins a way to hook into the test database initialization process
  2. Give the user a way to force a test database synchronization

While `test:prepare` is still a dependency of every test task, `db:test:prepare`
no longer hooks into it. This means that `test:prepare` runs before the schema
is synchronized. Plugins, which insert data can now hook into `db:test:prepare`.

The automatic schema maintenance can't detect when a migration is rolled-back,
modified and reapplied. In this case the user has to fall back to `db:test:prepare`
to force the synchronization to happen.

Fixes #17170

This method would assume that if last migration in the migrations
directory matched the current schema version, that the database was up
to date, but this does not account for new migrations with older
timestamps that may be pending.