= Migrant

== Summary

Migrant gives you a super-clean DSL to describe your ActiveRecord models (somewhat similar to DataMapper)
and generates all your migrations for you so you can spend more time coding the stuff that counts!

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

== Getting Started

Only for Rails 3 and Ruby 1.9+ folks. Simply install the gem "migrant", or add it to your bundler Gemfile
    
== Jumping right in

Start by creating some models with the structure you need:

  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          ["11 Test Drive", "Gardens", "Cape Town" ,"South Africa"].join("\n")
      date_established Time.now - 300.years
    end
  end

The best and easiest way is to provide example data and then Migrant will work out the appropriate 
column type for you.  You can also specify a symbol (like normal migrations), or just omit arguments
to get a good 'ol varchar(255). One more example model:

  class User < ActiveRecord::Base
    has_many :businesses
    
    structure do
      name        "John"
      surname     "Smith"
      description :string
    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
  
== Want more examples?

Check out the test models in test/rails_app/app/models/*
  
== What will happen seamlessly

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

== What won't

These actions won't be performed (because we don't want to hurt your data):

* Remove tables/columns 
* Changing column types where data loss may occur (e.g. varchar -> int)

== 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">

== 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
* To be implemented very soon - A :was => [:this,:then,:that] option to rename columns and add an alias method onto models (so as to not break existing code)
* 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

== License

Copyright (c) 2010 Pascal Houliston

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 from the gemspec, then to run tests do:

> rake test