`IPAddr` is used in `OID::Cidr`.

`Arel::Visitors::VISITORS` was removed at https://github.com/rails/arel/pull/412.

* 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

Follow up to #24079

    p PostgreSQLAdapter::OID::Money.precision
    # => 19

    p PostgreSQLAdapter::OID::Money.new.precision
    # => nil

This reverts commit ff835f90, reversing
changes made to c4d85dfb.

Reason: This broke the tests. We will add back after investigated.

These methods are private and unused from anywhere.

The default 'now'::date is CURRENT_DATE.

This is useful to libraries that want to feature gate based on the
version of PostgreSQL the user is connected to. For instance, I want to
know if the user is connected to a version of Postgres that supports
concurrent materialized view refreshes. I could add that as a method on
the adapter as a PR, but rails has no need for this itself.

Rails is already using the postgresql_version for its own feature gating
and this makes that possible for other libraries.

Since the attributes API is new in Rails 5, we don't actually need to keep
the behavior of `attribute :point`, as it's not a breaking change.

`pool` in args is unused anymore. And `config` is used in all adapters.

- 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

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.

- Addresses issue #12330

Overview
========

Cached postgres prepared statements become invalidated if the schema
changes in a way that it affects the returned result.

Examples:
- adding or removing a column then doing a 'SELECT *'
- removing the foo column  then doing a 'SELECT bar.foo'

In normal operation this isn't a problem, we can rescue the error,
deallocate the prepared statement and re-issue the command.

However in PostgreSQL transactions, once any command fails, the
transaction becomes 'poisoned' and any subsequent commands will raise
InFailedSQLTransaction.

This includes DEALLOCATE statements, so the default deallocation
strategy instead of removing the cached prepared statement instead
raises InFailedSQLTransaction.

Why this is bad
===============

1. InFailedSQLTransaction is a fairly cryptic error and doesn't
communicate any useful information about what has actually gone wrong.
2. In the naive implementation the prepared statement never gets
deallocated - it stays alive for the length of the session taking up
memory on the postgres server.
3. It is unsafe to retry the transaction because the bad prepared
statement is still in the cache and we would see the exact same failure
repeated.

Solution
========

If we are outside a transaction we can continue to handle these failures
gracefully in the usual way.

Inside a transaction instead of issuing a DEALLOCATE command that will
certainly fail, we now raise
ActiveRecord::PreparedStatementCacheExpired.

This can be handled further up the stack, notably inside
TransactionManager#within_new_transaction. Here we can make sure to
first rollback the transaction, then safely issue DEALLOCATE statements
to invalidate the rest of the cached prepared statements.

This also allows the user (or some gem) the opportunity to catch this error and
voluntarily retry the transaction if a schema change causes the prepared
statement cache to become invalidated.

Because the outdated statement has been deallocated, we can expect the
transaction to succeed on the second try.

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

In Postgres 8.1 the standard_conforming_strings setting was read-only,
meaning you got an error if you tried to update it. By filtering on
`context = 'user'` we only try to update the setting if it's
user-writable[1].

[1]: http://www.postgresql.org/docs/9.4/static/view-pg-settings.html

The standard_conforming_strings setting doesn't exist on all versions of
Postgres, but if it does exist, Rails turns it on. Previously this was done by
effectively disabling errors on the Postgres connection, issuing a SET to turn
the setting on, then re-enabling errors on the connection. However, if you're
running pgbouncer in transaction-pooling mode, you can't guarantee that
successive calls to `#execute` will be sent to the same pgbouncer-postgres
connection, so you can end up disabling errors on a different postgres
connection, and never re-enabling them. Future queries on that connection that
result in errors (e.g. violating unique constraints) will leave the connection
in a bad state where successive queries will fail.

This commit sets standard_conforming_strings by issuing an UPDATE to
pg_settings, which will update the setting if it exists, and do nothing if it
doesn't (rather than erroring out like SET would), which means we can remove
the error-disabling code.

It's also worth noting that Postgres has allowed standard_conforming_strings to
be updated since 8.2 (which is the oldest version Rails supports), so
technically we probably don't even need to be defensive here.

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

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

The returning_disabled configuration option is required to make postgresql partitioning triggers work. This commit fixes a bug where an invalid query would be made in cases where returning_disabled was true and objects were created with no attributes defined.

`@connection` in `StatementPool` is only used for PG adapter.
No need for abstract `StatementPool` class.

Several changes were made in #21110 which I am strongly opposed to.
(this is what I get for going on vacation. :trollface:) No type should
be introduced into the generic `ActiveRecord::Type` namespace, and
*certainly* should not be registered into the registry unconstrained
unless it is supported by *all* adapters (which basically means that it
was specified in the ANSI SQL standard).

I do not think `# :nodoc:` ing the type is sufficient, as it still makes
the code of Rails itself very unclear as to what the role of that class
is. While I would argue that this shouldn't even be a super class, and
that MySql and PG's JSON types are only superficially duplicated (they
might look the same but will change for different reasons in the
future).

However, I don't feel strongly enough about it as a point of contention
(and the biggest cost of harming the blameability has already occured),
so I simply moved the superclass into a namespace where its role is
absolutely clear.

After this change, `attribute :foo, :json` will once again work with
MySQL and PG, but not with Sqlite3 or any third party adapters.

Unresolved questions
--------------------

The types that and adapter publishes (at least those are unique to that
adapter, and not adding additional behavior like `MysqlString` should
probably be part of the adapter's public API. Should we standardize the
namespace for these, and document them?

As of MySQL 5.7.8, MySQL supports a native JSON data type.

Example:

    create_table :json_data_type do |t|
      t.json :settings
    end

This introduces a deprecation cycle to change the behavior of the
default point type in the PostgreSQL adapter. The old behavior will
continue to be available for the immediate future as `:legacy_point`.

The current behavior of returning an `Array` causes several problems,
the most significant of which is that we cannot differentiate between an
array of points, and a point itself in the case of a column with the
`point[]` type.

The attributes API gives us a reasonable way to have a proper
deprecation cycle for this change, so let's take advantage of it. If we
like this change, we can also add proper support for the other geometric
types (line, lseg, box, path, polygon, and circle), all of which are
just aliases for string today.

Fixes #20441

This line introduced by the commit fd398475 for using
`Arel::Visitors::BindVisitor`. Currently it is not used.

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