[ci skip] Fix Grammatical Errors and Eliminate Ambiguous Wordings in Multiple Database Documents (#41670)
* Improve Readability of Guides on Multiple Databases * Add comma after the introductory clause. * Add backtick for the symbols used in the program. * `primary` * `false` * Add descriptive information on ambiguous words. * users => database users * use the first configuration => use the first configuration as default * a recent write => a recent write by the requesting user * for an environment => for each environment * both a `role` and `shard` => both a `role` and a `shard` * Add missing period at the end of a sentence. * Add double quote inside backtick [Rafael Mendonça França + Takumasa Ochi]
This commit is contained in:
parent
cb95c1b14f
commit
9131f08904
|
@ -58,10 +58,10 @@ Let's add a replica for the first configuration, and a second database called an
|
||||||
replica for that as well. To do this we need to change our `database.yml` from a 2-tier
|
replica for that as well. To do this we need to change our `database.yml` from a 2-tier
|
||||||
to a 3-tier config.
|
to a 3-tier config.
|
||||||
|
|
||||||
If a primary configuration is provided this will be used as the "default" configuration. If
|
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 for an
|
there is no configuration named `"primary"`, Rails will use the first configuration as default
|
||||||
environment. The default configurations will use the default Rails filenames. For example
|
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 other entries
|
primary configurations will use `schema.rb` for the schema file, whereas all the other entries
|
||||||
will use `[CONFIGURATION_NAMESPACE]_schema.rb` for the filename.
|
will use `[CONFIGURATION_NAMESPACE]_schema.rb` for the filename.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
|
@ -91,7 +91,7 @@ production:
|
||||||
replica: true
|
replica: true
|
||||||
```
|
```
|
||||||
|
|
||||||
When using multiple databases there are a few important settings.
|
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 the `primary` and `primary_replica` should be the same because they contain
|
||||||
the same data. This is also the case for `animals` and `animals_replica`.
|
the same data. This is also the case for `animals` and `animals_replica`.
|
||||||
|
@ -99,11 +99,11 @@ 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
|
Second, the username for the writers and replicas should be different, and the
|
||||||
replica user's permissions should be set to only read and not write.
|
replica user's 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
|
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
|
`database.yml`. This is because Rails otherwise has no way of knowing which one is a replica
|
||||||
and which one is the writer.
|
and which one is the writer.
|
||||||
|
|
||||||
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` to the directory
|
||||||
where you will store migrations for that database. We'll look more at `migrations_paths`
|
where you will store migrations for that database. We'll look more at `migrations_paths`
|
||||||
later on in this guide.
|
later on in this guide.
|
||||||
|
|
||||||
|
@ -161,7 +161,7 @@ clients have a limit to the number of open connections there can be and if you d
|
||||||
multiply the number of connections you have since Rails uses the model class name for the
|
multiply the number of connections you have since Rails uses the model class name for the
|
||||||
connection specification name.
|
connection specification name.
|
||||||
|
|
||||||
Now that we have the `database.yml` and the new model set up it's time to create the databases.
|
Now that we have the `database.yml` and the new model set up, it's time to create the databases.
|
||||||
Rails 6.0 ships with all the rails tasks you need to use multiple databases in Rails.
|
Rails 6.0 ships with all the rails tasks you need to use multiple databases in Rails.
|
||||||
|
|
||||||
You can run `bin/rails -T` to see all the commands you're able to run. You should see the following:
|
You can run `bin/rails -T` to see all the commands you're able to run. You should see the following:
|
||||||
|
@ -192,7 +192,7 @@ rails db:schema:load:primary # Loads a database schema file (either
|
||||||
```
|
```
|
||||||
|
|
||||||
Running a command like `bin/rails db:create` will create both the primary and animals databases.
|
Running a command like `bin/rails db:create` will create both the primary and animals databases.
|
||||||
Note that there is no command for creating the users and you'll need to do that manually
|
Note that there is no command for creating the database users, and you'll need to do that manually
|
||||||
to support the readonly users for your replicas. If you want to create just the animals
|
to support the readonly users for your replicas. If you want to create just the animals
|
||||||
database you can run `bin/rails db:create:animals`.
|
database you can run `bin/rails db:create:animals`.
|
||||||
|
|
||||||
|
@ -213,7 +213,7 @@ $ bin/rails generate migration CreateDogs name:string --database animals
|
||||||
```
|
```
|
||||||
|
|
||||||
If you are using Rails generators, the scaffold and model generators will create the abstract
|
If you are using Rails generators, the scaffold and model generators will create the abstract
|
||||||
class for you. Simply pass the database key to the command line
|
class for you. Simply pass the database key to the command line.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$ bin/rails generate scaffold Dog name:string --database animals
|
$ bin/rails generate scaffold Dog name:string --database animals
|
||||||
|
@ -243,7 +243,7 @@ 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
|
Rails will only generate the new class once. It will not be overwritten by new scaffolds
|
||||||
or deleted if the scaffold is deleted.
|
or deleted if the scaffold is deleted.
|
||||||
|
|
||||||
If you already have an abstract class and its name differs from `AnimalsRecord` you can pass
|
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:
|
the `--parent` option to indicate you want a different abstract class:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
@ -255,11 +255,11 @@ use a different parent class.
|
||||||
|
|
||||||
## Activating automatic connection switching
|
## Activating automatic connection switching
|
||||||
|
|
||||||
Finally, in order to use the read-only replica in your application you'll need to activate
|
Finally, in order to use the read-only replica in your application, you'll need to activate
|
||||||
the middleware for automatic switching.
|
the middleware for automatic switching.
|
||||||
|
|
||||||
Automatic switching allows the application to switch from the writer to replica or replica
|
Automatic switching allows the application to switch from the writer to replica or replica
|
||||||
to writer based on the HTTP verb and whether there was a recent write.
|
to writer based on the HTTP verb and whether there was a recent write by the requesting user.
|
||||||
|
|
||||||
If the application is receiving a POST, PUT, DELETE, or PATCH request the application will
|
If the application is receiving a POST, PUT, DELETE, or PATCH request the application will
|
||||||
automatically write to the writer database. For the specified time after the write, the
|
automatically write to the writer database. For the specified time after the write, the
|
||||||
|
@ -371,7 +371,7 @@ end
|
||||||
```
|
```
|
||||||
|
|
||||||
Then models can swap connections manually via the `connected_to` API. If
|
Then models can swap connections manually via the `connected_to` API. If
|
||||||
using sharding both a `role` and `shard` must be passed:
|
using sharding, both a `role` and a `shard` must be passed:
|
||||||
|
|
||||||
```ruby
|
```ruby
|
||||||
ActiveRecord::Base.connected_to(role: :writing, shard: :default) do
|
ActiveRecord::Base.connected_to(role: :writing, shard: :default) do
|
||||||
|
@ -401,7 +401,7 @@ all databases globally. To use this feature you must first set
|
||||||
configuration. The majority of applications should not need to make any other
|
configuration. The majority of applications should not need to make any other
|
||||||
changes since the public APIs have the same behavior.
|
changes since the public APIs have the same behavior.
|
||||||
|
|
||||||
With `legacy_connection_handling` set to false, any abstract connection class
|
With `legacy_connection_handling` set to `false`, any abstract connection class
|
||||||
will be able to switch connections without affecting other connections. This
|
will be able to switch connections without affecting other connections. This
|
||||||
is useful for switching your `AnimalsRecord` queries to read from the replica
|
is useful for switching your `AnimalsRecord` queries to read from the replica
|
||||||
while ensuring your `ApplicationRecord` queries go to the primary.
|
while ensuring your `ApplicationRecord` queries go to the primary.
|
||||||
|
@ -458,6 +458,6 @@ will split the joins for you.
|
||||||
|
|
||||||
### Schema Cache
|
### Schema Cache
|
||||||
|
|
||||||
If you use a schema cache and multiple databases you'll need to write an initializer
|
If you use a schema cache and multiple databases, you'll need to write an initializer
|
||||||
that loads the schema cache from your app. This wasn't an issue we could resolve in
|
that loads the schema cache from your app. This wasn't an issue we could resolve in
|
||||||
time for Rails 6.0 but hope to have it in a future version soon.
|
time for Rails 6.0 but hope to have it in a future version soon.
|
||||||
|
|
Loading…
Reference in New Issue