-
Project: rubyforge.org/projects/migrator/
-
RDoc: migrator.rubyforge.org/
-
Github: github.com/aef/migrator/
Migrator is a Ruby library for building general purpose versioning systems in the style of ActiveRecord’s migrations.
-
Completely written in Ruby
-
Tested and fully working on:
-
Ubuntu Linux 8.10 amd64/x86_64
-
Ruby 1.8.7p72
-
Ruby 1.9.1p129
-
-
Debian GNU/Linux 4.0 x86
-
Ruby 1.8.6
-
-
On Windows XP x86
-
Ruby 1.8.6
-
-
Load the gem:
require 'aef/migrator'
Build an adapter:
class Adapter
include Aef::Migrator::Adapter
# version() has to reflect the current version. Also version=() must exist
# to set the current version
attr_accessor :version,
# versions() has to provide a list of all versions in correct order
attr_accessor :versions
def initialize
self.versions = %w{a b c d e}
self.version = 'c'
end
# process() has to do the work behind a migration in forward direction. Will
# be called multiple times for multistep migrations.
def process(target_version)
puts "Migrating from #{version} to #{target_version}"
self.version = target_version
end
# revert() has to do the work behind a migration in backward direction. Will
# be called multiple times for multistep migrations.
def revert(target_version)
puts "Unmigrating from #{version} to #{target_version}"
self.version = target_version
end
end
Notice that the module Aef::Migrator::Adapter and the class Aef::Migrator::AbstractAdapter both provide the basic method definitions for an adapter but no functionality. The advantage are better error messages when you forget to implement something, but you don’t have to use either, as Aef::Migrator defines an adapter only by checking for required methods.
Now we setup the migrator:
migrator = Aef::Migrator.new(Adapter.new)
After that we can use the versioning backend provided by the adapter to do migrations:
migrator.version # => "c" migrator.up migrator.version # => "d" migrator.up.version # => "e" migrator.down('b') migrator.version # => "b" migrator.migrate('e').version # => "e"
When migrations cannot be done, exceptions of the baseclass Aef::Migrator::Error are raised. If there is a problem with the Adapter the exceptions will be of Aef::Migrator::AdapterError which is a subclass of Aef::Migrator::Error. Exceptions informing about unmatched migration constraints are from the subclass Aef::Migrator::MigrationError.
We can also check if a migration is possible before running it. This way we don’t have to deal with exceptions when a migration cannot be done.
migrator.migratable?('e') # => false migrator.upable? # => false migrator.downable?('c') # => true
See the files in the spec subdirectory for further examples of usage.
-
rubygems
-
hoe (>= 2.3.2)
-
rspec (>= 1.2.8)
On *nix systems you may need to prefix the command with sudo to get root privileges.
There is a high security installation option available through rubygems. It is highly recommended over the normal installation, although it may be a bit less comfortable. To use the installation method, you will need my public key, which I use for cryptographic signatures on all my gems. You can find the public key and more detailed verification information in the aef-certificates section of my rubyforge project
Add the key to your rubygems’ trusted certificates by the following command:
gem cert --add aef.pem
Now you can install the gem while automatically verifying it’s signature by the following command:
gem install migrator --ignore-dependencies -P HighSecurity
Please notice that you may need other keys for dependent libraries, so you may have to install dependencies manually.
gem install migrator
Alternatively you could install migrator from github which may be a bit more up to date. The version may however not be as stable as the normal gem and there is no way to install the gem securely. Therefore this is not recommended.
gem install aef-migrator --source http://gems.github.com
You can test this package through rspec on your system. First find the path where the gem was installed to:
gem which aef/migrator
Go into the root directory of the installed gem and run the following command to start the test runner:
rake spec
If something goes wrong you should be noticed through failing examples.
This software is developed in the source code management system git hosted at github.com. You can download the most recent sourcecode through the following command:
git clone git://github.com/aef/migrator.git
Help on making this software better is always very appreciated. If you want your changes to be included in the official release, please send me a patch through the project’s tracker at rubyforge.org. You can generate a patch-file by the following command:
git diff > patch.diff
Please make sure to write tests for your changes and notice that I can’t promise to include your changes before reviewing them.
Copyright 2009 Alexander E. Fischer <aef@raxys.net>
This file is part of Migrator.
Migrator is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see <www.gnu.org/licenses/>.