Skip to content

Commit

Permalink
Add docs for abstract class generators
Browse files Browse the repository at this point in the history
Adds documentation for #39866
  • Loading branch information
eileencodes committed Jul 30, 2020
1 parent 9813543 commit aeab40b
Showing 1 changed file with 45 additions and 4 deletions.
49 changes: 45 additions & 4 deletions guides/source/active_record_multiple_databases.md
Expand Up @@ -93,11 +93,11 @@ Lastly, for new primary databases you need to set the `migrations_paths` to the
where you will store migrations for that database. We'll look more at `migrations_paths`
later on in this guide.

Now that we have a new database, let's set up the 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. In order to use the
new database we need to create a new abstract class and connect to the animals databases.

```ruby
class AnimalsBase < ApplicationRecord
class AnimalsRecord < ApplicationRecord
self.abstract_class = true

connects_to database: { writing: :animals, reading: :animals_replica }
Expand Down Expand Up @@ -171,7 +171,7 @@ Note that there is no command for creating the users and you'll need to do that
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`.

## Migrations
## Generators & Migrations

Migrations for multiple databases should live in their own folders prefixed with the
name of the database key in the configuration.
Expand All @@ -187,6 +187,47 @@ so that the file is generated in the correct directory. The command can be run l
$ bin/rails generate migration CreateDogs name:string --database animals
```

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

```bash
$ bin/rails generate scaffold Dog name:title --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`:

```ruby
class AnimalsRecord < ApplicationRecord
self.abstract_class = true

connects_to database: { writing: :animals }
end
```

The generated model will automatically inherit from `AnimalsRecord`.

```ruby
class Dog < AnimalsRecord
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.

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:

```bash
$ bin/rails generate scaffold Dog name:title --database animals --parent Animals::Record
```

This will skip generating `AnimalsRecord` since you've indicated to Rails that you want to
use a different parent class.

## Activating automatic connection switching

Finally, in order to use the read-only replica in your application you'll need to activate
Expand Down

0 comments on commit aeab40b

Please sign in to comment.