Migrant¶ ↑

Summary¶ ↑

Migrant gives you a clean DSL to describe your model schema (somewhat similar to DataMapper). It generates your migrations for you so you can spend more time describing your domain model cleanly and less time managing your database layer.

You’ll also get a handy .mock method to instantiate a filled-in model for testing or debugging.

Getting Started¶ ↑

In your Gemfile:

gem "migrant"

Jumping right in¶ ↑

Start by creating some models with the structure you need:

> rails generate migrant:model business

class Business < ActiveRecord::Base
  belongs_to :user

  # Here's where you describe the columns in your model
  structure do
    name             "The kernel's favourite fried chickens"
    website          "http://www.google.co.za/"
    address          :text
    date_established Time.now - 300.years
  end
end

Simply specify an example of the type of data you’ll be storing, and Migrant will work out the correct database schema for you. Note that you don’t need to specify foreign keys in the structure, they are automatically inferred from your relations. Here is a further example:

class User < ActiveRecord::Base
  has_many :businesses

  structure do
    name                                          # Don't specify any structure to get good 'ol varchar(255)
    surname     "Smith", :validates => :presence  # You can add your validations in here too to keep DRY
    description :string                           # Passing a symbol works like it does in add_column
    timestamps                                    # Gets you a created_at, and updated_at

    # Use an array to specifiy multiple validations
    secret_code 5521,    :validates => [:uniqueness, :numericality]
  end
end

Now, to get your database up to date simply run:

> rake db:upgrade

Wrote db/migrate/20101028192913_create_businesses.rb...
Wrote db/migrate/20101028192916_create_users.rb...

OR, if you’d prefer to look over the migrations yourself first, run:

> rails generate migrations

Result:

irb(main):001:0> Business
=> Business(id: integer, user_id: integer, name: string, website: string, address: text, date_established: datetime)

irb(main):002:0> Awesome!!!!
NoMethodError: undefined method `Awesome!!!!' for main:Object

By default, your database structure will be cloned to your test environment. If you don’t want this to happen automatically, simply specify an environment variable directly:

> rake db:upgrade RAILS_ENV=development

Serialization¶ ↑

Keeping track of your serialized attributes can be done in the Migrant DSL (v1.3+), here’s some examples:

class Business < ActiveRecord::Base
  structure do
    # Specify serialization automatically (e.g. using Hash, Array, OpenStruct)
    awards     ["Best Chicken 2007", "Business of the year 2008"]

    # Serialization by example types
    # This would load/store an OpenStruct but store as text in your database
    staff      :serialized, :example => OpenStruct.new("Manager" => "Joe")

    # Default serialization storage (hash)
    locations  :serialized
  end
end

These will call ActiveRecord::Base.serialize for you so don’t do it again yourself! The mock generated would appear as:

irb(main):002:0> my_business = Business.mock
=> #<Business id: nil, awards: ["Best Chicken 2007", "Business of the year 2008"], staff: #<OpenStruct manager="Joe">, 
     locations: {}>

Want more examples?¶ ↑

Check out the test models in test/rails_app/app/models/*

Model Generator¶ ↑

> rails generate migrant:model business name:string website:text

The model generator works as per the default ActiveRecord one, i.e. you can specify fields to be included in the model. However, a migration is not generated immediately, but the structure block in the model is automatically filled out for you.

Simply run rake db:upgrade or rails generate migrations to get the required migrations when you’re ready.

What will happen seamlessly¶ ↑

Creating tables or adding columns (as appropriate)
Adding indexes (happens on foreign keys automatically)
Validations (ActiveRecord 3)
Changing column types
Rollbacks for all the above

Compatibility¶ ↑

Officially supported: Ruby 1.9.3, 2.0.0, rbx-head
Unofficially supported: Ruby 1.8.7, 1.9.2
Rails 3.0 (all versions)
Rails 4.0 (only from v1.4.3 onwards)

Getting a mock of your model¶ ↑

> rails console

irb(main):002:0> my_business = Business.mock
=> #<Business id: nil, name: "The Kernel's favourite fried chickens", website: "http://www.google.co.za/",
     address: "11 Test Drive\nGardens\nCape Town\nSouth Africa", date_established: "1710-10-28 21:03:31">

irb(main):003:0> my_business.user
=> #<User id: nil, name: "John", surname: "Smith", description: "Some string">

Pickle/Cucumber Integration¶ ↑

Add the following to support/env/pickle.rb:

require 'pickle/migrant'
Pickle.configure do |config|
 config.adapters = [Pickle::Migrant]
end

All pickle steps will then return a mocked model by default, overriden with any values you provide.

Help¶ ↑

Be sure to check out the Github Wiki, or give me a shout on Twitter: @101pascal

Maintability / Usability concerns¶ ↑

You don’t have to define a structure on every model, Migrant ignores models with no definitions
You can remove the structure definitions later and nothing bad will happen (besides losing automigration for those fields)
If you have a model with relations but no columns, you can still have migrations generated by adding “no_structure” or define a blank structure block.
It’s probably a good idea to review the generated migrations before committing to SCM, just to check there’s nothing left out.

Roadmap / Planned features¶ ↑

Rake task to consolidate a given set of migrations (a lot of people like to do this once in a while to keep migration levels sane)
Fabricator/Factory integration/seperation - Need to assess how useful this is, then optimize or kill.

License¶ ↑

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Development¶ ↑

Please be sure to install all the development dependencies via Bundler, then to run tests do:

> rake test

Simplecov reports will be generated for each run. If it’s not at 100% line coverage, something’s wrong!

speed-of-light/migrant