JT Hopple LLC

Reliable Migrations

Jeremy • Programming, Rails, Ruby • Digg!

Ruby on Rails migrations rule! They're easy to get started with and have changed the way I approach database-driven application development. However, I was recently shocked when I used capistrano to deploy a new version of an application and one of the migrations exploded. It turns out that using ActiveRecords in your migrations can lead to unexpected results, but by following two simple guidelines you can ensure that your migrations will remain reliable throughout your application's life-cycle.

Migrations are primarily used for two things: 1) to alter the database schema, and 2) to move data around. Using ActiveRecord models in migrations is an incredibly powerful and productive way to make data adjustments after having altered the schema, but this practice can backfire.

The following guidelines will ensure that migrations remain reliable even when they use ActiveRecord models:

  1. Always reset the column information for an ActiveRecord after having altered it's table.
  2. If you plan to use ActiveRecords in your migration, define them locally in the migration.

In one of our applications, we were convinced that we needed a "sophisticated" role-based user authentication system, but after getting real with the application we quickly realized that a much simpler user system would work. So, we wrote the following migration to remove the more complicated role-based system in favor of a simple admin boolean in the users table:

  1. class simplify_users < ActiveRecord::Migration
  2. def self.up
  3. add_column :users, :admin, :boolean, :default => false
  5. User.find(:all).each do |user|
  6. user.update_attribute(:admin, true) if user.roles.include?(Role.find_by_name("admin"))
  7. end
  9. drop_table :roles
  10. drop_table :user_roles
  11. end
  13. def self.down
  14. create_table :roles do |t|
  15. t.column :name, :string
  16. end
  18. create table :user_roles do |t|
  19. t.column :user_id, :integer, :null => false
  20. t.column :role_id, :integer, :null => false
  21. end
  23. remove_column :users, :admin
  24. end
  25. end

There are two problems with this migration. The first problem is that we've added a new column to the users table and then we attempt to use the User model to update this attribute. If this migration is run by itself, everything will run fine as the column information for the ActiveRecord, User in this case, is loaded the first time it is referenced. However, if this migration isn't run by itself and the User model was referenced in a previous migration we'll get an error, "NoMethodError: undefined method 'admin' for User."

Fixing this problem is easy and illustrates our first guideline. Always reset the column information for an ActiveRecord after having altered it's table (line 7):

  1. class simplify_users < ActiveRecord::Migration
  2. def self.up
  3. add_column :users, :admin, :boolean, :default => false
  5. #since we altered the users table, we need to reset the column
  6. #information prior to using the User model
  7. User.reset_column_information
  9. User.find(:all).each do |user|
  10. user.update_attribute(:admin, true) if user.roles.include?(Role.find_by_name("admin"))
  11. end
  13. drop_table :roles
  14. drop_table :user_roles
  15. end
  17. def self.down
  18. create_table :roles do |t|
  19. t.column :name, :string
  20. end
  22. create table :user_roles do |t|
  23. t.column :user_id, :integer, :null => false
  24. t.column :role_id, :integer, :null => false
  25. end
  27. remove_column :users, :admin
  28. end
  29. end

The second problem has to do with the fact that we're assuming that the ActiveRecord models we're using in our migration actually exist. In the case of our example migration we dropped the roles and user_roles tables and removed the User and UserRole models from our application (and our svn repository). Since these models no longer existed, our migration failed with "NameError: uninitialized constant UserType." This leads us to our second guideline. If you plan to use ActiveRecords in your migration, define them locally in the migration (lines 4-13):

  1. class simplify_users < ActiveRecord::Migration
  2. #since we need to use both the User and Role models in this migration,
  3. #let's define them here along with the relationships we'll need to use.
  4. class User < ActiveRecord::Base
  5. has_many :roles, :through => :user_roles
  6. end
  8. class UserRole < ActiveRecord::Base
  9. belongs_to :user
  10. belongs_to :role
  11. end
  13. class Role < ActiveRecord::Base; end
  15. def self.up
  16. add_column :users, :admin, :boolean, :default => false
  18. #since we altered the users table, we need to reset the column
  19. #information prior to using the User model
  20. User.reset_column_information
  22. User.find(:all).each do |user|
  23. user.update_attribute(:admin, true) if user.roles.include?(Role.find_by_name("admin"))
  24. end
  26. drop_table :roles
  27. drop_table :user_roles
  28. end
  30. def self.down
  31. create_table :roles do |t|
  32. t.column :name, :string
  33. end
  35. create table :user_roles do |t|
  36. t.column :user_id, :integer, :null => false
  37. t.column :role_id, :integer, :null => false
  38. end
  40. remove_column :users, :admin
  41. end
  42. end

By defining the ActiveRecords locally in the migration, you can be certain that the migration will run successfully regardless of whether the model still exists in the application. Also, as you may have noticed by the fact that the User has_many roles, it is necessary that you specify any relationships that you plan to use in your migration in your local ActiveRecord definitions. This may seem like a hassle, but, in addition to running into problems if you try to use an ActiveRecord that doesn't exist anymore, you can also run into problems by using relationships, methods, or attributes that don't exist in the ActiveRecord anymore.

The bottom line is that migrations are meant to run on any version of your database and upgrade it to the current version (or whichever version you specify). You just have to keep in mind that the source of your application could be drastically different at the time you run your migrations than when you created them. Following the guidelines outlined here will help you ensure that your migrations remain reliable.

References: Screencast: Migrating data and schema , The Joy of Migrations , Safely using models in migrations

Back to recent articles . . .

0 Comments

Post a comment