- 2.1 The Entire App Inside a Component
- 2.2 ActiveRecord and Handling Migrations within Components
- 2.3 Handling Dependencies within Components
This chapter is from the book
This chapter is from the book
This chapter is from the book
2.2 ActiveRecord and Handling Migrations within Components
Let’s add some actual functionality to our currently bare-bones application. The first feature we are going to focus on is for the app to be able to predict the outcome of future games based on past performances. To this end, we will add teams and games as models to AppComponent. We will create an admin interface for both teams and games, which will give us enough data to try our hand at predicting some games.
Remember to execute these commands in the context of AppComponent, that is, under ./components/app_component.
Scaffolding Team and Game. Execute in ./components/app_component
$ rails g scaffold team name:string
$ rails g scaffold game date:datetime location:string first_team_id:integer
second_team_id:integer winning_team:integer first_team_score:integer second_team_score:integer
The next step is to run rake db:migrate to create the appropriate tables in the database. Interestingly, this will work when called within ./components/app_component, but not in ./. It does not fail for the main app. It just doesn’t do anything.
Scaffolding Team and Game. Execute in ./components/app_component
$ rake db:migrate == 20171029235211 CreateAppComponentTeams: migrating ================ -- create_table(:app_component_teams) -> 0.0005s == 20171029235211 CreateAppComponentTeams: migrated (0.0006s) ======= == 20171029235221 CreateAppComponentGames: migrating ================ -- create_table(:app_component_games) -> 0.0007s == 20171029235221 CreateAppComponentGames: migrated (0.0007s) ======= $ cd ../.. $ rake db:migrate Running via Spring preloader in process 58196
Before this will work, we need to make the main app aware of the migrations provided by the engine.
2.2.1 Installing Engine Migrations with Rake
The common solution to this is to install the engine’s migrations into the main app with rake app_component:install:migrations. This will copy all the migrations found in the engine’s db/migrate folder into that of the main app.
There are a few gems out there that use this functionality. For example, the gem Commontator (https://github.com/lml/commontator) does this. Most widely used gems, like ActiveAdmin (http://activeadmin.info/) and Devise (http://devise.plataformatec.com.br/), generate more complex migrations in the host app. They don’t actually come with migrations of their own, but instead use generators to create them based on user-specified configuration options.
If we were to run rake app_component:install:migrations in the Sportsball app, we would get the following contents in the engine and the main app:
Install engine migrations into the main app. Execute in ./
$ rake app_component:install:migrations Running via Spring preloader in process 58464 Copied migration 20171030000159_create_app_component_teams. app_component.rb from app_component Copied migration 20171030000160_create_app_component_games. app_component.rb from app_component
AppComponent engine migrations
$ tree ./components/app_component/db/migrate components/app_component/db/migrate20171029235211_create_app_component_teams.rb
20171029235221_create_app_component_games.rb
Sportsball application migrations
$ tree ./db/migrate ./db/migrate
While the original migrations in the engine are still present, the rake task has copied them into the main app. In doing so, it renamed them and changed their date to the current time. This ensures that the engine’s migrations are being run as the last ones in the application (“last” at the time they are installed into the app).
The re-dating of migrations to the current time is very important for engines that are intended to be distributed (like the ones mentioned previously), because it is unknown when the gem, and thus its migrations, are going to be added to an application. If the dates were not changed, there would be no control over where in the overall migration sequence they would fall. However, since the gem had to have been published before the development of the app (or the relevant portion of the app) was started, they are likely going to be run very early. That, in turn, would likely lead to an invalid overall migration state on any system that runs the app—even production: While newer migrations have run, older ones are missing.
Note that rake railties:install:migrations installs all new migrations from all engines in an application. If migrations are added after the installer has run, it will need to be run again to ensure all migrations are present.
Having to install migrations every time they are added to an engine is an extra step in comparison to what we are used to. And, as discussed previously, the reason it is needed in many situations (gems being developed independently from applications) does not hold true in our case. It turns out that we can change our engine to have the host Rails application automatically find and use its migrations.
2.2.2 Loading Engine Migrations in Place
Instead of copying migrations from components into the main application, we can ensure that the main app can find them with a few lines of code added to the component’s engine.rb. This technique was first suggested by Ben Smith (http://pivotallabs.com/leave-your-migrations-in-your-rails-engines/).
./components/app_component/lib/app_component/engine.rb – Engine migrations configuration
1 module AppComponent
2 class Engine < ::Rails::Engine
3 isolate_namespace AppComponent
4
5 initializer :append_migrations do |app|
6 unless app.root.to_s.match root.to_s+File::SEPARATOR
7 app.config.paths["db/migrate"].concat(
config.paths["db/migrate"].expanded)
8 end
9 end
10 end
11 end
Now rake db:migrate will find and correctly run the engine’s migrations.
It is important not to use migration installation rake tasks in combination with this technique and to remove what may have been added while following the previous section. That would result in problems with migrations being loaded twice, which is similar to something we will see next.
2.2.3 Known Issues
There are a few snags you can run into with this approach that should be avoided.
2.2.3.1 Chaining db:migrate in Rake Tasks Fails to Add
For a still unknown reason, rake db:drop db:create db:migrate works fine for a normal Rails app, but fails to add the migrations when engine migrations are loaded in place. The simplest way around this is to split this command in two by running rake db:drop db:create && rake db:migrate instead. This has performance implications, as the rake now has to load twice.
Ben Smith proposes a few different fixes for this issue, the most concise being to require the Rails environment to be loaded before the db:load_config by adding the following file db.rake:
./components/app_component/lib/tasks/db.rake
1 Rake::Task["db:load_config"].enhance [:environment]
This has the side effect of the environment (i.e., the Rails app’s contents) always being loaded before any database tasks are run. Not only does this have a performance implication, it also affects every environment. And while the pattern rake db:drop db:create db:migrate is common in development, it will never be called in the production environment. In my opinion, it is a bad tradeoff to affect production in unknown ways to achieve small benefits in development.
In conclusion, I recommend working around the problem instead of using a solution that is not fully understood. This issue should be fixed by understanding and fixing the true cause in whatever it is that Rails does to run migrations. That would also make a nice pull request to Rails for the one who finds it!
2.2.3.2 Other Rake Tasks Reported Not Working
It has been reported that other database-related tasks, like rake db:setup, rake db:rollback, and rake db:migration:redo, stop working with this approach. I have never been able to confirm this and it certainly works in the Sportsball app as we have created it so far.
2.2.3.3 Problems with Naming Engines
In the code snippet that adds the engine’s migrations, you may have noticed the peculiar line unless app.root.to_s.match root.to_s+File::SEPARATOR. It prevents a problem with running rake app_component:db:migrate inside the engine itself, which throws the following error otherwise:
Engine migrations loaded twice through dummy app. Executed in ./components/app_component (if the check is removed)
$ rake app_component:db:migrate rake aborted! ActiveRecord::DuplicateMigrationNameError: Multiple migrations have the name CreateAppComponentTeams
The match is a heuristic to determine whether the engine is currently being loaded within its own dummy app. If that is the case, the initializer should not add the routes, as they are added automatically. The heuristic fails if the dummy app of the engine is outside of its own directory structure, which should never be the case.
A less powerful version of this heuristic evaluates app.root.to_s.match root.to_s, which fails if used with two engines where the name of the including engine starts with the name of the included engine and they are in the same directory. For example, if /components/users_server depends on /components/users, the former matches the latter and will not load its migrations. The more robust version of the heuristic should be used to prevent this problem.
2.2.3.4 Conclusion
We have added models for Team and Game and we have ensured that migrations can be run in the main application. Do so, if you haven’t yet, and start the server.
Run migrations and start the server. Executed in ./
$ rake db:migrate Running via Spring preloader in process 58740 == 20171029235211 CreateAppComponentTeams: migrating ================= -- create_table(:app_component_teams) -> 0.0010s == 20171029235211 CreateAppComponentTeams: migrated (0.0010s) ======== == 20171029235221 CreateAppComponentGames: migrating ================= -- create_table(:app_component_games) -> 0.0007s == 20171029235221 CreateAppComponentGames: migrated (0.0007s) ======== $ rails s => Booting Puma => Rails 5.1.4 application starting in development => Run `rails server -h` for more startup options Puma starting in single mode... * Version 3.10.0 (ruby 2.4.2-p198), codename: Russell's Teapot * Min threads: 5, max threads: 5 * Environment: development * Listening on tcp://0.0.0.0:3000 Use Ctrl-C to stop
With this, we can reach the UI for teams and games by navigating to http://localhost:3000/teams and http://localhost:3000/games, respectively. There, we are greeted with the standard look of scaffolded admin pages, as shown for teams in Figures 2.3 and 2.4.
)
Figure 2.3. List of teams with two teams already added
)
Figure 2.4. Adding a new team