Chris@909: # Contains the enhancements to Rails' migrations system to support the 
Chris@909: # Engines::Plugin::Migrator. See Engines::RailsExtensions::Migrations for more
Chris@909: # information.
Chris@909: 
Chris@909: require "engines/plugin/migrator"
Chris@909: 
Chris@909: # = Plugins and Migrations: Background
Chris@909: #
Chris@909: # Rails uses migrations to describe changes to the databases as your application
Chris@909: # evolves. Each change to your application - adding and removing models, most
Chris@909: # commonly - might require tweaks to your schema in the form of new tables, or new
Chris@909: # columns on existing tables, or possibly the removal of tables or columns. Migrations
Chris@909: # can even include arbitrary code to *transform* data as the underlying schema
Chris@909: # changes.
Chris@909: # 
Chris@909: # The point is that at any particular stage in your application's development, 
Chris@909: # migrations serve to transform the database into a state where it is compatible
Chris@909: # and appropriate at that time.
Chris@909: # 
Chris@909: # == What about plugins?
Chris@909: # 
Chris@909: # If you want to share models using plugins, chances are that you might also
Chris@909: # want to include the corresponding migrations to create tables for those models.
Chris@909: # With the engines plugin installed, plugins can carry migration data easily:
Chris@909: # 
Chris@909: #   vendor/
Chris@909: #     |
Chris@909: #     plugins/
Chris@909: #       |
Chris@909: #       my_plugin/
Chris@909: #         |- init.rb
Chris@909: #         |- lib/
Chris@909: #         |- db/
Chris@909: #             |-migrate/
Chris@909: #                 |- 20081105123419_add_some_new_feature.rb
Chris@909: #                 |- 20081107144959_and_something_else.rb
Chris@909: #                 |- ...
Chris@909: # 
Chris@909: # When you install a plugin which contains migrations, you are undertaking a
Chris@909: # further step in the development of your application, the same as the addition
Chris@909: # of any other code. With this in mind, you may want to 'roll back' the
Chris@909: # installation of this plugin at some point, and the database should be able
Chris@909: # to migrate back to the point without this plugin in it too.
Chris@909: #
Chris@909: # == An example
Chris@909: #
Chris@909: # For example, our current application is at version 20081106164503 (according to the
Chris@909: # +schema_migrations+ table), when we decide that we want to add a tagging plugin. The
Chris@909: # tagging plugin chosen includes migrations to create the tables it requires
Chris@909: # (say, _tags_ and _taggings_, for instance), along with the models and helpers
Chris@909: # one might expect.
Chris@909: #
Chris@909: # After installing this plugin, these tables should be created in our database.
Chris@909: # Rather than running the migrations directly from the plugin, they should be
Chris@909: # integrated into our main migration stream in order to accurately reflect the
Chris@909: # state of our application's database *at this moment in time*.
Chris@909: #
Chris@909: #   $ script/generate plugin_migration
Chris@909: #         exists  db/migrate
Chris@909: #         create  db/migrate/20081108120415_my_plugin_to_version_20081107144959.rb
Chris@909: #
Chris@909: # This migration will take our application to version 20081108120415, and contains the 
Chris@909: # following, typical migration code:
Chris@909: # 
Chris@909: #   class TaggingToVersion20081107144959 < ActiveRecord::Migration
Chris@909: #     def self.up
Chris@909: #       Engines.plugins[:tagging].migrate(20081107144959)
Chris@909: #     end
Chris@909: #     def self.down
Chris@909: #       Engines.plugins[:tagging].migrate(0)
Chris@909: #     end
Chris@909: #   end
Chris@909: #
Chris@909: # When we migrate our application up, using <tt>rake db:migrate</tt> as normal,
Chris@909: # the plugin will be migrated up to its latest version (20081108120415 in this example). If we
Chris@909: # ever decide to migrate the application back to the state it was in at version 20081106164503,
Chris@909: # the plugin migrations will be taken back down to version 0 (which, typically,
Chris@909: # would remove all tables the plugin migrations define).
Chris@909: #
Chris@909: # == Upgrading plugins
Chris@909: #
Chris@909: # It might happen that later in an application's life, we update to a new version of
Chris@909: # the tagging plugin which requires some changes to our database. The tagging plugin
Chris@909: # provides these changes in the form of its own migrations. 
Chris@909: #
Chris@909: # In this case, we just need to re-run the plugin_migration generator to create a 
Chris@909: # new migration from the current revision to the newest one:
Chris@909: #
Chris@909: #   $ script/generate plugin_migration
Chris@909: #        exists db/migrate
Chris@909: #        create db/migrate/20081210131437_tagging_to_version_20081201172034.rb
Chris@909: #
Chris@909: # The contents of this migration are:
Chris@909: #
Chris@909: #   class TaggingToVersion20081108120415 < ActiveRecord::Migration
Chris@909: #     def self.up
Chris@909: #       Engines.plugins[:tagging].migrate(20081201172034)
Chris@909: #     end
Chris@909: #     def self.down
Chris@909: #       Engines.plugins[:tagging].migrate(20081107144959)
Chris@909: #     end
Chris@909: #   end
Chris@909: #
Chris@909: # Notice that if we were to migrate down to revision 20081108120415 or lower, the tagging plugin
Chris@909: # will be migrated back down to version 20081107144959 - the version we were previously at.
Chris@909: #
Chris@909: #
Chris@909: # = Creating migrations in plugins
Chris@909: #
Chris@909: # In order to use the plugin migration functionality that engines provides, a plugin 
Chris@909: # only needs to provide regular migrations in a <tt>db/migrate</tt> folder within it.
Chris@909: #
Chris@909: # = Explicitly migrating plugins
Chris@909: #
Chris@909: # It's possible to migrate plugins within your own migrations, or any other code.
Chris@909: # Simply get the Plugin instance, and its Plugin#migrate method with the version
Chris@909: # you wish to end up at:
Chris@909: #
Chris@909: #   Engines.plugins[:whatever].migrate(version)
Chris@909: #
Chris@909: #
Chris@909: # = Upgrading from previous versions of the engines plugin
Chris@909: #
Chris@909: # Thanks to the tireless work of the plugin developer community, we can now relying on the migration 
Chris@909: # mechanism in Rails 2.1+ to do much of the plugin migration work for us. This also means that we
Chris@909: # don't need a seperate schema_info table for plugins.
Chris@909: #
Chris@909: # To update your application, run
Chris@909: #
Chris@909: #   rake db:migrate:upgrade_plugin_migrations
Chris@909: #
Chris@909: # This will ensure that migration information is carried over into the main schema_migrations table.
Chris@909: #