The default timestamp used for AR is `updated_at` in nanoseconds! (:nsec) This causes issues on any machine that runs an OS that supports nanoseconds timestamps, i.e. not-OS X, where the cache_key of the record persisted in the database (milliseconds precision) is out-of-sync with the cache_key in the ruby VM.

This commit adds:

A test that shows the issue, it can be found in the separate file `cache_key_test.rb`, because
- model couldn't be defined inline
- transactional testing needed to be turned off to get it to pass the MySQL tests
This seemed cleaner than putting it in an existing testcase file.

It adds :usec as a dateformat that calculates datetime in microseconds

It sets precision of cache_key to :usec instead of :nsec, as no db supports nsec precision on timestamps

Remove mentioned of 'readonly' options in doc for HABTM [ci skip]

`each_with_object` allocates an array for each kv pair.  Switching to
the slightly more verbose but less allocatey `each_pair` eliminates
array allocations.  Eliminating this allocation returns AR objects to
have constant array allocations regardless of the number of columns the
object has.

Here is test code:

```ruby
require 'active_record'

class Topic < ActiveRecord::Base
end

20.times do |i|
  Process.waitpid fork {
    ActiveRecord::Base.establish_connection adapter: 'sqlite3', database: ':memory:'

    ActiveRecord::Base.connection.instance_eval do
      create_table(:topics) do |t|
        t.string   :title, limit: 250
        t.string   :author_name
        t.string   :author_email_address
        t.string   :parent_title
        t.string   :type
        t.string   :group
        i.times do |j|
          t.string :"aaa#{j}"
        end
        t.timestamps null: true
      end
    end

    ObjectSpace::AllocationTracer.setup(%i{type})

    Topic.create title: "aaron" # heat cache

    result = ObjectSpace::AllocationTracer.trace do
      10.times do |i|
        Topic.create title: "aaron #{i}"
      end
    end

    puts "#{Topic.columns.length},#{(result.find { |k,v| k.first == :T_ARRAY }.last.first / 10)}"
  }
end
```

Before this commit:

```
9,166
10,167
11,168
12,169
13,170
14,171
15,172
16,173
17,174
18,175
19,176
20,177
21,178
22,179
23,180
24,181
25,182
26,183
27,184
28,185
```

After:

```
9,157
10,157
11,157
12,157
13,157
14,157
15,157
16,157
17,157
18,157
19,157
20,157
21,157
22,157
23,157
24,157
25,157
26,157
27,157
28,157
```

Left side is the number of columns, right is the number of allocations

Clarifies db can be set up from structure.sql as well as from schema.rb

Add 'db/'; corrects structure.rb to structure.sql

deep_dup'ing a hash will dup the keys as well as the values.  Since
string keys from the source hash will be frozen, and the dup'd objects
are immediately dup'd and frozen on insert in to the hash, the end user
will only ever see two frozen strings.  Since the strings are immutable,
this commit just cheats a little and reuses the immutable strings.

Just to reiterate, before this commit, deep duping a hash that looks
like this: `{ "foo" => "bar" }` will generate two new instances of
"foo". One is created when `deep_dup` is called on "foo", and the other
is created when the newly allocated "foo" string is inserted in to the
hash.  The user never sees the intermediate "foo", and both copies of
"foo" that the user *can* access will be frozen, so in this case we just
reuse the existing frozen key.

The upshot is that after this change, string allocations on AR
allocations become constant regardless of the number of columns the
model has.

```ruby
require 'active_record'

class Topic < ActiveRecord::Base
end

20.times do |i|
  Process.waitpid fork {
    ActiveRecord::Base.establish_connection adapter: 'sqlite3', database: ':memory:'

    ActiveRecord::Base.connection.instance_eval do
      create_table(:topics) do |t|
        t.string   :title, limit: 250
        t.string   :author_name
        t.string   :author_email_address
        t.string   :parent_title
        t.string   :type
        t.string   :group
        i.times do |j|
          t.integer :"aaa#{j}"
        end
        t.timestamps null: true
      end
    end

    ObjectSpace::AllocationTracer.setup(%i{type})

    Topic.create title: "aaron" # heat cache

    result = ObjectSpace::AllocationTracer.trace do
      10.times do |i|
        Topic.create title: "aaron #{i}"
      end
    end

    puts "#{Topic.columns.length},#{(result.find { |k,v| k.first == :T_STRING }.last.first / 10)}"
  }
end
```

If you run the above script before this commit, the output looks like
this:

```
[aaron@TC rails (master)]$ be ruby -rallocation_tracer test.rb
9,105
10,107
11,109
12,111
13,113
14,115
15,117
16,119
17,121
18,123
19,125
20,127
21,129
22,131
23,133
24,135
25,137
26,139
27,141
28,143
```

The left column is the number of methods, the right column is the number
of string allocations.

Running against this commit, the output is:

```
[aaron@TC rails (master)]$ be ruby -rallocation_tracer test.rb
9,87
10,87
11,87
12,87
13,87
14,87
15,87
16,87
17,87
18,87
19,87
20,87
21,87
22,87
23,87
24,87
25,87
26,87
27,87
28,87
```

As you can see, there is now only a constant number of strings
allocated, regardless of the number of columns the model has.

Expand support for ActiveSupport::TimeWithZone#utc?

I seriously don't even know why we handle booleans, but those strings
should technically be frozen. Additionally, we don't need to actually
check the class in the mutable string type, since the `cast_value`
function will always return a string.

This type adds an escape hatch to apps for which string duping causes
unacceptable memory growth. The reason we are duping them is in order to
detect mutation, which was a feature added to 4.2 in #15674. The string
type was modified to support this behavior in #15788.

Memory growth is really only a concern for string types, as it's the
only mutable type where the act of coersion does not create a new object
regardless (as we're usually returning an object of a different class).

I do feel strongly that if we are going to support detecting mutation,
we should do it universally for any type which is mutable. While it is
less common and ideomatic to mutate strings than arrays or hashes, there
shouldn't be rules or gotchas to understanding our behavior.

However, I also appreciate that for apps which are using a lot of string
columns, this would increase the number of allocations by a large
factor. To ensure that we keep our contract, if you'd like to opt out of
mutation detection on strings, you'll also be option out of mutation of
those strings.

I'm not completely married to the thought that strings coming out of
this actually need to be frozen -- and I think the name is correct
either way, as the purpose of this is to provide a string type which
does not detect mutation.

In the new implementation, I'm only overriding `cast_value`. I did not
port over the duping in `serialize`. I cannot think of a reason we'd
need to dup the string there, and the tests pass without it.
Unfortunately that line was introduced at a time where I was not nearly
as good about writing my commit messages, so I have no context as to
why I added it. Thanks past Sean. You are a jerk.

Currently, ActiveSupport::TimeWithZone#utc? simply runs a check to see
if the linked ActiveSupport::TimeZone's name is "UTC". This will only
return true for ActiveSupport::TimeZone["UTC"], but not for time zones
such as "Etc/UTC", "Etc/Universal", or other time zones that are aliases
for UTC. Interestingly enough, ActiveSupport::TimeWithZone#utc? is also
aliased as #gmt? but will return false for the "GMT" timezone (along
with other TZInfo aliases for GMT).

Instead of running a simple check on the TimeZone name, we can rely on
the underlying TZInfo::TimezonePeriod and TZInfo::TimezoneOffset which
keep a record of of the offset's abbreviated name. The possibilities
here for UTC time zones are `:UTC`, `:UCT`, and `:GMT`.
Signed-off-by: NDavid <me@davidcel.is>

Better deprecation warning for `ActiveRecord::Relation#update`

I added that *structure.sql* file can be used when *db:reset* is run.

*db:reset* tasks states *db:reset* loads database from *db/schema.rb*
or *db/structure.sql* depending on the configuration (although
*db/schema.rb* is the default), hence the change.

When passing an instance of `ActiveRecord::Base` to `#update`, it would
internally call `#find`, resulting in a misleading deprecation warning.

This change gives this deprecated use of `#update` its own, meaningful
warning.

Dirty checking keeps a hash where the keys are the column name and the
value is a dup of the value from the database[1].  This hash is kept for
every AR object, which means that we dup every column name for every AR
object that does dirty checking.  Freezing the column name prevents the
column name from being duped and reduced overall string allocations.

Here is a benchmark to demonstrate:

```ruby
require 'active_record'

class Topic < ActiveRecord::Base
end

20.times do |i|
  Process.waitpid fork {
    ActiveRecord::Base.establish_connection adapter: 'sqlite3', database: ':memory:'

    ActiveRecord::Base.connection.instance_eval do
      create_table(:topics) do |t|
        t.string   :title, limit: 250
        t.string   :author_name
        t.string   :author_email_address
        t.string   :parent_title
        t.string   :type
        t.string   :group
        i.times do |j|
          t.string :"aaa#{j}"
        end
        t.timestamps null: true
      end
    end

    ObjectSpace::AllocationTracer.setup(%i{type})

    Topic.create title: "aaron" # heat cache

    result = ObjectSpace::AllocationTracer.trace do
      10.times do |i|
        Topic.create title: "aaron #{i}"
      end
    end

    puts "#{Topic.columns.length},#{(result.find { |k,v| k.first == :T_STRING }.last.first / 10)}"
  }
end
```

1. https://github.com/rails/rails/blob/3ad381c3f8598d9920998c8949a96b5f62b280dd/activerecord/lib/active_record/attribute_set/builder.rb#L102

migrations Class methods have nodoc, fix it for API [ci skip]

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

Documentation ActiveRecord Attributes API code fix

add application_job.rb to template of mountable engine

Fix formatting of ActiveRecord PostgreSQL guide.

Add basic support for access control headers to ActionDispatch::Static

Only prepend a single module when defining deprecation wrappers.

I could not find any reason why each method got its own prepended
module here, and all tests appear to pass with my change.

The rdoc parser seems to trip on the `private def` construct.
Public methods following a method defined with `private def` are not
visible inside the module docs but are appended to the top-most module.

For example the method `ActiveRecord::QueryMethods#distinct` was listed
under `ActiveRecord#distinct`.

/cc @sgrif

[ci skip]

This class is only used internally. We should keep it out of public
documentation. This patch adds nodoc for
`ActiveRecord::Associations::Builder` and everything nested within.

This error is raised in certain situations when eager loading
polymorphic associations. We even mention it in our docs. It should be
included in our API.

Conflicts:
	activerecord/lib/active_record/associations.rb

Also unify the format of code example output. Only use `# =>` if the
actual return value is described. Otherwise simply use `#`.

Conflicts:
	activerecord/lib/active_record/relation/query_methods.rb