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

Example:

    create_table :foos do |t|
      t.string :string_en, collation: 'en_US.UTF-8'
      t.text   :text_ja,   collation: 'ja_JP.UTF-8'
    end

https://github.com/ruby/ruby/pull/579 - there is a new optimization
since ruby 2.2

Previously regexp patterns were faster (since a string was converted to
regexp underneath anyway). But now string patterns are faster and
better reflect the purpose.

  Benchmark.ips do |bm|
    bm.report('regexp') { 'this is ::a random string'.gsub(/::/, '/') }
    bm.report('string') { 'this is ::a random string'.gsub('::', '/') }
    bm.compare!
  end
  # string: 753724.4 i/s
  # regexp: 501443.1 i/s - 1.50x slower

We were never clearing the `PG::Result` object used to query the types
when the connection is first established. This would lead to a
potentially large amount of memory being retained for the life of the
connection.

Investigating this issue also revealed several low hanging fruit on the
performance of these methods, and the number of allocations has been
reduced by ~90%.

Fixes #19578

This makes the connection adapter future-proof regarding to new parameters.

To maintain backward compatibility, :requiressl is added by hand. It is
deprecated by PostgreSQL since 2003, but still accepted by libpq.

This obsoletes the ruby based implementations.

The type map was introduced in aafee233, but wasn't properly filled.

This mainly adjusts many locations, that expected strings instead of
integers or boolean.

add_pg_decoders is moved after setup of the StatementPool, because
execute_and_clear could potentially make use of it.

Ruby-pg's default way to serialize values for transmission to the database is to
call #to_s . This however creates a temporary String object for each value.
Setting a class based type map avoids the allocation of this additional String.

The performance benefit is measurable in microbenchmarks, but not with
the overhead of activerecord. However it's free to use and has no drawback.

Versions of the pg gem earlier than 0.18.0 cannot be used safely with Ruby 2.2.
Specifically, pg 0.17 when used with Ruby 2.2 has a known bug that causes
random bits to be added to the end of strings. Further explanation here:
https://bitbucket.org/ged/ruby-pg/issue/210/crazy-bytes-being-added-to-record

The cause by which the test suite for the mysql adapter broke in 1502caef
(reverted 89ba5bb4) is because the precision was not extracted.

The rounding problem in mysql adapter has not been fixed, but `mysql_56`
helper tested only mysql2 adapter, its behavior was not apparent.

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

We do this in the adapter classes specifically, so the types aren't
registered if we don't use that adapter. Constants under the PostgreSQL
namespace for example are never loaded if we're using mysql.