hummingbird 0.0.1

data/.gitignore

@@ -0,0 +1,16 @@
+# Packaged Gem
+/pkg/
+
+# Developer specific files & editor cruft
+Gemfile.lock
+.rvmrc
+.*.sw?
+\#*\#
+.\#*
+*~
+
+# SimpleCov
+/coverage/
+
+# OS X
+.DS_Store

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - "1.9.2"
+  - "1.9.3"

data/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+# Want to help?
+
+We'd love to have your help!  Found a bug?  Have a documentation fix?
+Fixed a bug?  Great!  Everything helps.  Please feel free to file
+issues in the [issue tracker][issues], and open pull requests.
+
+[issues]: https://github.com/jhelwig/hummingbird/issues "GitHub issue tracker"

data/Gemfile

@@ -0,0 +1,15 @@
+require 'rbconfig'
+
+source :rubygems
+gemspec
+
+group :development do
+  platform = RbConfig::CONFIG['host_os'] rescue Config::CONFIG['host_os']
+
+  case platform
+  when /darwin/
+    gem 'rb-fsevent', :require => false
+  when /linux/
+    gem 'rb-inotify', :require => false
+  end
+end

data/Guardfile

@@ -0,0 +1,9 @@
+# More info at https://github.com/guard/guard#readme
+ignore /^coverage\//
+
+guard 'minitest' do
+  # with Minitest::Unit
+  watch(/^test\/(.*)\/?(.*)_test\.rb/)
+  watch(/^(lib\/.*)([^\/]+)\.rb/)      { |m| "test/#{m[1]}#{m[2]}_test.rb" }
+  watch(/^test\/test_helper\.rb/)      { "test" }
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Jacob Helwig <jacob@technosorcery.net>
+
+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.

data/README.md

@@ -0,0 +1,134 @@
+# What is it?
+
+Hummingbird is a way to write SQL migrations in SQL, and provide
+some minimal tooling around running these migrations against a DB.
+
+# Why is it?
+
+DSLs that abstract away the differences in databases can be nice to
+work with, but they often cater to something resembling the lowest
+common denominator amongst those databases.
+
+# How to use it
+
+## Configuration
+
+Hummingbird will look for a `hummingbird.yml` in the directory passed
+to `Hummingbird::Configuration.new`.  Hummingbird will also look for a
+user-specific `.hummingbird.yml` in the current working directory.
+The user-specific configuration file will take precidence over the
+configuration in the `hummingbird.yml`.
+
+Both of these configuration files are YAML files with the following
+format:
+
+```YAML
+---
+basedir: 'sql'
+planfile: 'application.plan'
+migrations_dir: 'migrations'
+migrations_table: 'application_migrations'
+connection_string: 'sqlite://db/database.db'
+```
+
+* `basedir`: The `planfile`, and `migrations_dir` settings are relative
+  to this directory, which is relative to the current working
+  directory.
+* `planfile`: Described more below. This determines the order in which
+  migration files are run.
+* `migrations_dir`: This is the name of the directory that will
+  contain all of the migrations.  All files in this directory are
+  considered to be migration files, and Hummingbird will recurse into
+  any and all subdirectories starting here.
+* `connection_string`: This is a [Sequel][] compatible connection
+  string for connecting to the database.
+
+The above example configures Hummingbird to look in the file
+`sql/application.plan` for the list of migrations to run, in the
+directory `sql/migrations` for all of the migration files, use the
+table named `application_migrations` within the database, and to
+connect to the database using the [Sequel][] connection string `'sqlite://db/database.db'`.
+
+## Boot-strapping the Database
+
+Hummingbird is capable of bootstrapping itself into the database to be
+managed as long as the first migration creates the table named by the
+`migrations_table` configuration option.  This table will need to have
+a `migration_name` column of type `TEXT` (or similar data type to
+handle the maximum file path relative to `migrations_dir`), and a
+`run_on` column of type `INTEGER`.
+
+The following is an example for defining the `migrations_table` for
+SQLite3:
+
+```sql
+CREATE TABLE hummingbird_migrations (
+  migration_name TEXT PRIMARY KEY,
+  run_on INTEGER
+);
+
+```
+
+## Plan file
+
+The plan file contains the names of the migration files to be run, one
+per line, in the order that they should be run.
+
+Given the following plan file and the example configuration from above:
+
+```
+bootstrap.sql
+stored_procedures/foo.sql
+tables/bar.sql
+```
+
+Hummingbird would attempt to run the files
+`sql/migrations/bootstrap.sql`,
+`sql/migrations/stored_procedures/foo.sql`,
+`sql/migrations/tables/bar.sql` in exactly this order.
+
+## Running migrations
+
+Right now, only just enough is written to enable someone to write
+their own rake task, or other glue code to actually migrate their
+database using Hummingbird.
+
+This isn't really a great way to go about it, but you can do the
+following in your `Rakefile` at least until the rest of the glue is
+included in Hummingbird itself:
+
+```Ruby
+desc 'Migrate the database'
+task "migrate" do
+  require 'hummingbird'
+
+  config = Hummingbird::Configuration.new(Dir.getwd)
+  plan   = Hummingbird::Plan.new(config.planfile, config.migrations_dir)
+  db     = Hummingbird::Database.new(config.connection_string, config.migrations_table)
+
+  unplanned_files = plan.files_missing_from_plan
+  fail "Found migration files not listed in #{config.planfile}: #{unplanned_files.join(', ')}" unless unplanned_files.empty?
+
+  missing_files = plan.files_missing_from_migration_dir
+  fail "Found planned migration files not in migrations directory: #{missing_files.join(', ')}" unless missing_files.empty?
+
+  migrations_already_run = db.already_run_migrations
+  migrations_to_run      = plan.migrations_to_be_run(migrations_already_run)
+
+  puts "#{plan.planned_files.count} migrations planned; #{migrations_already_run.count} already run; #{migrations_to_run.count} to run"
+
+  migrations_to_run.each do |migration|
+    puts "Running migration: #{migration[:migration_name]}"
+    db.run_migration(migration[:migration_name], migration[:sql])
+  end
+end
+```
+
+# Resources
+
+* [Travis CI][travis-ci] [![Build Status](https://secure.travis-ci.org/jhelwig/hummingbird.png?branch=master)](http://travis-ci.org/jhelwig/hummingbird)
+* [Issues][issues]
+
+[travis-ci]: http://travis-ci.org "Travis CI"
+[issues]: https://github.com/jhelwig/hummingbird/issues "GitHub issues"
+[Sequel]: http://sequel.rubyforge.org/ "The Database Toolkit for Ruby"

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList[File.join('test','lib','hummingbird','**','*_test.rb')]
+  t.verbose = true
+end
+
+task :default => :test

data/hummingbird.gemspec

@@ -0,0 +1,31 @@
+# -*- encoding: utf-8 -*-
+require File.join(File.dirname(__FILE__), File.join('lib', 'hummingbird', 'version'))
+
+Gem::Specification.new do |gem|
+  gem.name                  = 'hummingbird'
+  gem.version               = Hummingbird::VERSION
+  gem.license               = 'MIT'
+  gem.authors               = ['Jacob Helwig']
+  gem.email                 = ['jacob@technosorcery.net']
+  gem.description           = %q{Write your DB migrations in SQL and run them, hold the magic.}
+  gem.summary               = <<-DESC
+No DSL, as little magic as possible.  Write your DB migrations in SQL,
+and run them in the order specified by a plan file.
+DESC
+  gem.homepage              = 'http://github.com/jhelwig/hummingbird'
+  gem.executables           = `git ls-tree --name-only -r -z HEAD #{File.join("bin","*")}`.split("\0").map{ |f| File.basename(f) }
+  gem.files                 = `git ls-tree --name-only -r -z HEAD`.split("\0")
+  gem.test_files            = `git ls-tree --name-only -r -z HEAD #{File.join("test","*")}`.split("\0")
+  gem.require_paths         = ['lib']
+  gem.required_ruby_version = '>= 1.8.7'
+
+  gem.add_dependency 'sequel'
+  gem.add_dependency 'optimism'
+
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'minitest'
+  gem.add_development_dependency 'guard'
+  gem.add_development_dependency 'guard-minitest'
+  gem.add_development_dependency 'simplecov'
+  gem.add_development_dependency 'sqlite3'
+end

data/lib/hummingbird/configuration.rb

@@ -0,0 +1,35 @@
+require 'optimism'
+
+class Hummingbird
+  class Configuration
+    CONFIG_FILE = 'hummingbird.yml'
+    USER_CONFIG_FILE = '.hummingbird.yml'
+
+    def initialize(config_dir)
+      @config = Optimism.require(
+        File.expand_path(File.join(config_dir, CONFIG_FILE)),
+        File.expand_path(File.join(FileUtils.pwd, USER_CONFIG_FILE))
+      )
+    end
+
+    def basedir
+      @basedir ||= @config[:basedir] || '.'
+    end
+
+    def planfile
+      @planfile ||= File.expand_path(File.join(basedir, @config[:planfile] || 'hummingbird.plan'))
+    end
+
+    def migrations_dir
+      @migrations_dir ||= File.expand_path(File.join(basedir, @config[:migrations_dir] || 'migrations'))
+    end
+
+    def migrations_table
+      @migrations_table ||= (@config[:migrations_table] || :hummingbird_migrations).to_sym
+    end
+
+    def connection_string
+      @connection_string ||= @config[:connection_string]
+    end
+  end
+end

data/lib/hummingbird/database.rb

@@ -0,0 +1,31 @@
+require 'sequel'
+
+class Hummingbird
+  class Database
+    def initialize(connection_string, migrations_table)
+      @sequel_db                     = Sequel.connect(connection_string)
+      @migrations_table_name         = migrations_table
+      @prepared_run_migration_insert = nil
+    end
+
+    def initialized?
+      @sequel_db.tables.include?(@migrations_table_name)
+    end
+
+    def already_run_migrations
+      initialized? ? @sequel_db[@migrations_table_name].order(:run_on).to_a : []
+    end
+
+    def run_migration(name,sql)
+      @prepared_run_migration_insert ||= @sequel_db[@migrations_table_name].prepare(:insert, :record_migration, migration_name: :$name, run_on: :$date)
+
+      @sequel_db.transaction do
+        @sequel_db.execute(sql)
+
+        @prepared_run_migration_insert.call(name: name, date: DateTime.now.strftime('%s'))
+      end
+
+      true
+    end
+  end
+end

data/lib/hummingbird/plan.rb

@@ -0,0 +1,75 @@
+require 'hummingbird/plan_error'
+
+require 'pathname'
+
+class Hummingbird
+  class Plan
+    attr_reader :migration_dir, :planned_files
+
+    def initialize(planfile, migration_dir)
+      @planned_files = parse_plan(planfile)
+      @migration_dir = migration_dir
+    end
+
+    def migration_files
+      @migration_files ||= get_migration_files
+    end
+
+    def files_missing_from_plan
+      migration_files - planned_files
+    end
+
+    def files_missing_from_migration_dir
+      planned_files - migration_files
+    end
+
+    def migrations_to_be_run(already_run_migrations)
+      to_be_run_migration_file_names(already_run_migrations).map do |f|
+        {
+          migration_name: f,
+          sql: get_migration_contents(f)
+        }
+      end
+    end
+
+    def to_be_run_migration_file_names(already_run_migrations)
+      return planned_files if already_run_migrations.empty?
+
+      unless (run_migrations_missing_from_plan = already_run_migrations.map {|a| a[:migration_name]} - planned_files).empty?
+        raise Hummingbird::PlanError.new("Plan is missing the following already run migrations: #{run_migrations_missing_from_plan.join(', ')}",planned_files,already_run_migrations)
+      end
+
+      files = planned_files.dup
+      already_run_migrations.each do |f|
+        if f[:migration_name] == files.first
+          files.shift
+        else
+          first_out_of_sync_run_on = DateTime.strptime(f[:run_on].to_s, '%s')
+
+          raise Hummingbird::PlanError.new("Plan has '#{files.first}' before '#{f[:migration_name]}' which was run on #{first_out_of_sync_run_on}",planned_files,already_run_migrations)
+        end
+      end
+
+      files
+    end
+
+    def get_migration_contents(migration_file)
+      File.read(File.absolute_path(migration_file, @migration_dir))
+    end
+
+    private
+
+    def parse_plan(planfile)
+      File.read(planfile).split("\n")
+    end
+
+    def get_migration_files
+      listing = Dir[File.join(migration_dir,'**','*')].select {|f| File.file? f}
+
+      migration_path = Pathname.new(migration_dir)
+      listing.map do |f|
+        Pathname.new(f).relative_path_from(migration_path).to_s
+      end
+    end
+  end
+end

data/lib/hummingbird/plan_error.rb

@@ -0,0 +1,11 @@
+class Hummingbird
+  class PlanError < Exception
+    attr_reader :already_run_migrations, :planned_files
+
+    def initialize(msg,planned_files,already_run_migrations)
+      super(msg)
+      @planned_files = planned_files
+      @already_run_migrations = already_run_migrations
+    end
+  end
+end

data/lib/hummingbird/version.rb

@@ -0,0 +1,3 @@
+class Hummingbird
+  VERSION = "0.0.1"
+end

data/lib/hummingbird.rb

@@ -0,0 +1,7 @@
+require 'hummingbird/version'
+require 'hummingbird/configuration'
+require 'hummingbird/plan'
+require 'hummingbird/database'
+
+class Hummingbird
+end

data/test/fixtures/basic_config.yml

@@ -0,0 +1,6 @@
+---
+basedir: 'sql'
+planfile: 'application.plan'
+migrations_dir: 'migrations-dir'
+migrations_table: 'application_migrations'
+connection_string: 'sequel connection string'

data/test/fixtures/no_basedir_config.yml

@@ -0,0 +1,3 @@
+---
+planfile: 'application.plan'
+migrations_dir: 'migrations'