Copy-edit pass on the multiple databases guide

Main points:

* Applies our documentation guidelines (names of files, punctuation in comments, etc.)

* AnimalsRecord was introduced before the primary abstract class. Before this
  point, stuff related to the primary database is explained first, and then you
  go for the extra database. This is the natural order, I think. I reordered
  for consistency.

* PrimaryApplicationRecord was missing connects_to.

* Fixes parent class for the example related to PrimaryApplicationRecord.

Author: fxn

guides/source/active_record_multiple_databases.md

@@ -39,7 +39,7 @@ Let's say we have an application with a single writer database, and we need to a
 new database for some new tables we're adding. The name of the new database will be
 "animals".
 
-The `database.yml` looks like this:
+`config/database.yml` looks like this:
 
 ```yaml
 production:
@@ -49,15 +49,15 @@ production:
   password: <%= ENV['ROOT_PASSWORD'] %>
 ```
 
-Let's add a second database called animals and replicas for both databases as well. To do
-this, we need to change our `database.yml` from a 2-tier
-to a 3-tier config.
+Let's add a second database called "animals" and replicas for both databases as
+well. To do this, we need to change our `config/database.yml` from a 2-tier to a
+3-tier config.
 
-If a primary configuration is provided, it will be used as the "default" configuration. If
-there is no configuration named `"primary"`, Rails will use the first configuration as default
+If a `primary` configuration key is provided, it will be used as the "default" configuration. If
+there is no configuration named `primary`, Rails will use the first configuration as default
 for each environment. The default configurations will use the default Rails filenames. For example,
-primary configurations will use `schema.rb` for the schema file, whereas all the other entries
-will use `[CONFIGURATION_NAMESPACE]_schema.rb` for the filename.
+primary configurations will use `db/schema.rb` for the schema file, whereas all the other entries
+will use `db/[CONFIGURATION_NAMESPACE]_schema.rb` for the filename.
 
 ```yaml
 production:
@@ -88,35 +88,26 @@ production:
 
 When using multiple databases, there are a few important settings.
 
-First, the database name for the `primary` and `primary_replica` should be the same because they contain
+First, the database name for `primary` and `primary_replica` should be the same because they contain
 the same data. This is also the case for `animals` and `animals_replica`.
 
 Second, the username for the writers and replicas should be different, and the
 replica user's database permissions should be set to only read and not write.
 
-When using a replica database, you need to add a `replica: true` entry to the replica in the
-`database.yml`. This is because Rails otherwise has no way of knowing which one is a replica
+When using a replica database, you need to add a `replica: true` entry to the replica in
+`config/database.yml`. This is because Rails otherwise has no way of knowing which one is a replica
 and which one is the writer. Rails will not run certain tasks, such as migrations, against replicas.
 
-Lastly, for new writer databases, you need to set the `migrations_paths` to the directory
+Lastly, for new writer databases, you need to set the `migrations_paths` key to the directory
 where you will store migrations for that database. We'll look more at `migrations_paths`
 later on in this guide.
 
 You can also configure the schema dump file by setting `schema_dump` to a custom schema file name
 or completely skip the schema dumping by setting `schema_dump: false`.
 
-Now that we have a new database, let's set up the connection model. In order to use the
-new database we need to create a new abstract class and connect to the animals databases.
+Now that we have a new database, let's set up the connection model.
 
-```ruby
-class AnimalsRecord < ApplicationRecord
-  self.abstract_class = true
-
-  connects_to database: { writing: :animals, reading: :animals_replica }
-end
-```
-
-Then we need to update `ApplicationRecord` to be aware of our new replica.
+The primary database replica may be configured in `ApplicationRecord` this way:
 
 ```ruby
 class ApplicationRecord < ActiveRecord::Base
@@ -133,18 +124,39 @@ should share a connection with.
 ```ruby
 class PrimaryApplicationRecord < ActiveRecord::Base
   primary_abstract_class
+
+  connects_to database: { writing: :primary, reading: :primary_replica }
 end
 ```
 
-Classes that connect to primary/primary_replica can inherit from your primary abstract
-class like standard Rails applications:
+In that case, classes that connect to `primary`/`primary_replica` can inherit
+from your primary abstract class like standard Rails applications do with
+`ApplicationRecord`:
 
 ```ruby
-class Person < ApplicationRecord
+class Person < PrimaryApplicationRecord
 end
 ```
 
-By default Rails expects the database roles to be `writing` and `reading` for the primary
+On the other hand, we need to setup our models persisted in the "animals" database:
+
+```ruby
+class AnimalsRecord < ApplicationRecord
+  self.abstract_class = true
+
+  connects_to database: { writing: :animals, reading: :animals_replica }
+end
+```
+
+Those models should inherit from that common abstract class:
+
+```ruby
+class Car < AnimalsRecord
+  # Talks automatically to the animals database.
+end
+```
+
+By default, Rails expects the database roles to be `writing` and `reading` for the primary
 and replica respectively. If you have a legacy system you may already have roles set up that
 you don't want to change. In that case you can set a new role name in your application config.
 
@@ -159,8 +171,9 @@ clients have a limit to the number of open connections there can be, and if you
 multiply the number of connections you have since Rails uses the model class name for the
 connection specification name.
 
-Now that we have the `database.yml` and the new model set up, it's time to create the databases.
-Rails ships with all the commands you need to use multiple databases.
+Now that we have the `config/database.yml` and the new model set up, it's time
+to create the databases. Rails ships with all the commands you need to use
+multiple databases.
 
 You can run `bin/rails --help` to see all the commands you're able to run. You should see the following:
 
@@ -225,8 +238,8 @@ production:
 Migrations for multiple databases should live in their own folders prefixed with the
 name of the database key in the configuration.
 
-You also need to set the `migrations_paths` in the database configurations to tell Rails
-where to find the migrations.
+You also need to set `migrations_paths` in the database configurations to tell
+Rails where to find the migrations.
 
 For example the `animals` database would look for migrations in the `db/animals_migrate` directory and
 `primary` would look in `db/migrate`. Rails generators now take a `--database` option
@@ -243,8 +256,8 @@ class for you. Simply pass the database key to the command line.
 $ bin/rails generate scaffold Dog name:string --database animals
 ```
 
-A class with the database name and `Record` will be created. In this example
-the database is `Animals` so we end up with `AnimalsRecord`:
+A class with the camelized database name and `Record` will be created. In this
+example the database is "animals" so we end up with `AnimalsRecord`:
 
 ```ruby
 class AnimalsRecord < ApplicationRecord
@@ -264,8 +277,8 @@ end
 NOTE: Since Rails doesn't know which database is the replica for your writer you will need to
 add this to the abstract class after you're done.
 
-Rails will only generate the new class once. It will not be overwritten by new scaffolds
-or deleted if the scaffold is deleted.
+Rails will only generate `AnimalsRecord` once. It will not be overwritten by new
+scaffolds or deleted if the scaffold is deleted.
 
 If you already have an abstract class and its name differs from `AnimalsRecord`, you can pass
 the `--parent` option to indicate you want a different abstract class:
@@ -366,7 +379,7 @@ need.
 
 ```ruby
 ActiveRecord::Base.connected_to(role: :reading) do
-  # all code in this block will be connected to the reading role
+  # All code in this block will be connected to the reading role.
 end
 ```
 
@@ -381,11 +394,11 @@ like `connected_to(role: :nonexistent)` you will get an error that says
 
 If you want Rails to ensure any queries performed are read only, pass `prevent_writes: true`.
 This just prevents queries that look like writes from being sent to the database.
-You should also configure your replica database to run in readonly mode.
+You should also configure your replica database to run in read-only mode.
 
 ```ruby
 ActiveRecord::Base.connected_to(role: :reading, prevent_writes: true) do
-  # Rails will check each query to ensure it's a read query
+  # Rails will check each query to ensure it's a read query.
 end
 ```
 
@@ -474,7 +487,7 @@ role and the shard with the `connected_to` API.
 
 ```ruby
 ActiveRecord::Base.connected_to(role: :reading, shard: :shard_one) do
-  Person.first # Lookup record from read replica of shard one
+  Person.first # Lookup record from read replica of shard one.
 end
 ```
 
@@ -483,12 +496,12 @@ end
 Applications are able to automatically switch shards per request using the provided
 middleware.
 
-The `ShardSelector` Middleware provides a framework for automatically
+The `ShardSelector` middleware provides a framework for automatically
 swapping shards. Rails provides a basic framework to determine which
 shard to switch to and allows for applications to write custom strategies
 for swapping if needed.
 
-The `ShardSelector` takes a set of options (currently only `lock` is supported)
+`ShardSelector` takes a set of options (currently only `lock` is supported)
 that can be used by the middleware to alter behavior. `lock` is
 true by default and will prohibit the request from switching shards once
 inside the block. If `lock` is false, then shard swapping will be allowed.
@@ -502,7 +515,7 @@ automatic shard swapping:
 $ bin/rails g active_record:multi_db
 ```
 
-Then in the file uncomment the following:
+Then in the generated `config/initializers/multi_db.rb` uncomment the following:
 
 ```ruby
 Rails.application.configure do
@@ -524,8 +537,8 @@ config.active_record.shard_resolver = ->(request) {
 
 ## Granular Database Connection Switching
 
-In Rails 6.1 it's possible to switch connections for one database instead of
-all databases globally.
+Starting from Rails 6.1, it's possible to switch connections for one database
+instead of all databases globally.
 
 With granular database connection switching, any abstract connection class
 will be able to switch connections without affecting other connections. This
@@ -534,27 +547,30 @@ while ensuring your `ApplicationRecord` queries go to the primary.
 
 ```ruby
 AnimalsRecord.connected_to(role: :reading) do
-  Dog.first # Reads from animals_replica
-  Person.first  # Reads from primary
+  Dog.first # Reads from animals_replica.
+  Person.first  # Reads from primary.
 end
 ```
 
 It's also possible to swap connections granularly for shards.
 
 ```ruby
 AnimalsRecord.connected_to(role: :reading, shard: :shard_one) do
-  Dog.first # Will read from shard_one_replica. If no connection exists for shard_one_replica,
-  # a ConnectionNotEstablished error will be raised
-  Person.first # Will read from primary writer
+  # Will read from shard_one_replica. If no connection exists for shard_one_replica,
+  # a ConnectionNotEstablished error will be raised.
+  Dog.first
+
+  # Will read from primary writer.
+  Person.first
 end
 ```
 
 To switch only the primary database cluster use `ApplicationRecord`:
 
 ```ruby
 ApplicationRecord.connected_to(role: :reading, shard: :shard_one) do
-  Person.first # Reads from primary_shard_one_replica
-  Dog.first # Reads from animals_primary
+  Person.first # Reads from primary_shard_one_replica.
+  Dog.first # Reads from animals_primary.
 end
 ```
 
@@ -619,13 +635,17 @@ There are some important things to be aware of with this option:
 
 ### Schema Caching
 
-If you want to load a schema cache for each database you must set a `schema_cache_path` in each database configuration and set `config.active_record.lazily_load_schema_cache = true` in your application configuration. Note that this will lazily load the cache when the database connections are established.
+If you want to load a schema cache for each database you must set
+`schema_cache_path` in each database configuration and set
+`config.active_record.lazily_load_schema_cache = true` in your application
+configuration. Note that this will lazily load the cache when the database
+connections are established.
 
 ## Caveats
 
 ### Load Balancing Replicas
 
-Rails also doesn't support automatic load balancing of replicas. This is very
-dependent on your infrastructure. We may implement basic, primitive load balancing
-in the future, but for an application at scale this should be something your application
-handles outside of Rails.
+Rails doesn't support automatic load balancing of replicas. This is very
+dependent on your infrastructure. We may implement basic, primitive load
+balancing in the future, but for an application at scale this should be
+something your application handles outside of Rails.