dbmule 0.1.0 → 0.1.1

data/README.markdown

@@ -1,200 +1,200 @@
-Rails migrations in non-Rails (and non Ruby) projects.
+## Mule
 
-WHAT'S NEW
-==========
-In the 2.x release we have moved to using Rails 3 migrations instead of maintaining our own migration related code. Just about anything you can do with Rails 3 migrations you can now do with [Standalone Migrations](https://github.com/thuss/standalone-migrations) too! This removed 95% of the code we have to maintain. Big thanks to [Ricardo Valeriano](http://ricardovaleriano.com/) and [Michael Grosser](http://pragmatig.wordpress.com) for undertaking this major rewrite!
+###What is it?
 
-CONTRIBUTE
-==========
-[Standalone Migrations](https://github.com/thuss/standalone-migrations) relies on the contributions of the open-source community! To submit a fix or an enhancement fork the repository, checkout the *develop* branch, make your changes, add your name to the *Contributors* section in README.markdown, and send us a pull request! If you're active and do good work we'll add you as a collaborator!
+Mule is a database migration tool based on a stand-alone version of [Rails Migrations](http://guides.rubyonrails.org/migrations.html). By default, Mule uses SQL scripts instead of Migrations DSL, so no Ruby coding is required. It supports multi-database environments, including support for existing databases.
 
-USAGE
-=====
-Install Ruby, RubyGems and a ruby-database driver (e.g. `gem install mysql`) then:
+You interact with Mule via a series of [Rake](http://rake.rubyforge.org/) commands which map almost 1:1 to Rails Migrations commands, so if you are familiar with them you will be right at home, but if not, don't worry -- it's really easy.
 
-    $ gem install standalone_migrations
+These commands give you a simple, yet powerful toolset allowing you to manage database migrations across both development and production environments.
 
-Add to `Rakefile` in your projects base directory:
+###How do I use it?
+
+####Prerequisites
+
+Before using Mule, you must set up a Ruby environment on your machine. Follow the instructions at the links for [Ruby](http://www.ruby-lang.org/en/downloads/) and [RubyGems](https://rubygems.org/pages/download).
+
+Once you have both Ruby and RubyGems installed, you should install the Ruby database driver for whatever database you are using, for example:
+
+PostgreSQL
+
+    $ gem install pg
+
+####Installation
+
+Once your Ruby environment is set up, installing Mule is no big deal:
+
+    $ gem install dbmule
+
+Next, create a `Rakefile` in your project's base directory containing the following lines:
 
 ```ruby
-require 'standalone_migrations'
-StandaloneMigrations::Tasks.load_tasks
+require 'mule_migrations'
+MuleMigrations::Tasks.load_tasks
 ```
 
-Add database configuration to `db/config.yml` in your projects base directory e.g.:
+Installation is complete, you are now ready to begin using Mule.
+
+####Create a database project
+
+To begin, create a new database project. A database project represents one database in your system. You can do this with one command:
+
+    rake mule:new_project db=foo_bar_database
+
+Mule will then create a directory in your project's base directory called whatever you put in for `foo_bar_database` above. Inside it will create the basic Mule project structure, which looks like this:
+
+    foo_bar_database/
+      db/
+        migrate/
+        sql/
+        seeds/
+        config.yml
+        seeds.rb
+
+After the project has been created, you will need to edit the `foo_bar_database\db\config.yml` file and enter the correct database connection information for each environment section you require (development, test, production below). You can create an arbitary number of environments, with any names you like:
 
     development:
-      adapter: sqlite3
-      database: db/development.sqlite3
+      adapter: postgresql
+      encoding: unicode
+      database: foo_bar_database_development
       pool: 5
-      timeout: 5000
+      username:
+      password:
+      host: localhost
 
-    production:
-      adapter: mysql
-      encoding: utf8
-      reconnect: false
-      database: somedatabase_dev
+    test:
+      adapter: postgresql
+      encoding: unicode
+      database: foo_bar_database_test
       pool: 5
-      username: root
+      username:
       password:
-      socket: /var/run/mysqld/mysqld.sock
+      host: localhost
 
-    test: &test
-      adapter: sqlite3
-      database: db/test.sqlite3
+    production:
+      adapter: postgresql
+      encoding: unicode
+      database: foo_bar_database_production
       pool: 5
-      timeout: 5000
+      username: ENV['FOO_BAR_DATABASE_USER']
+      password: ENV['FOO_BAR_DATABASE_PSWD']
+      host: ENV['FOO_BAR_DATABASE_HOST']
 
-### To create a new database migration:
+####Changing the current environment
 
-    rake db:new_migration name=foo_bar_migration
-    edit db/migrate/20081220234130_foo_bar_migration.rb
+Any command you run will default to the `development` environment, but you can specify which environment you want to run using RAILS_ENV:
 
-#### If you really want to, you can just execute raw SQL:
+    $ rake mule:migrate db=foo_bar_database RAILS_ENV=production
 
-```ruby
-def up
-  execute "insert into foo values (123,'something');"
-end
+####Enable migrations on an existing database
 
-def down
-  execute "delete from foo where field='something';"
-end
-```
+Sometimes you will need to create a database project for an existing database. To do so, follow the instructions above for creating a project and then run the following command: 
 
-### To apply your newest migration:
+    $ rake mule:configure_existing_database db=foo_bar_database
 
-    rake db:migrate
+This will add an initial database version to your database with the contents of a schema dump, so that it can be recreated in other environments.
 
-### To migrate to a specific version (for example to rollback)
+####Create a migration:
 
-    rake db:migrate VERSION=20081220234130
+    $ rake mule:new_migration db=foo_bar_database name=foo_bar_migration
 
-### To migrate a specific database (for example your "testing" database)
+A migration represents a single change you want to make in the database, such as adding a table, adding a column, creating an index, dropping a column, dropping a database, dropping an index, defining a stored procedure...and so on. 
 
-    rake db:migrate DB=test ... or ...
-    rake db:migrate RAILS_ENV=test
+A migration has both an UP and DOWN implementation: UP to make the change and DOWN to undo it. When you call the command above, by default Mule will create two SQL scripts in the `foo_bar_database/db/sql` directory. The format of the filenames are:
 
-### To execute a specific up/down of one single migration
+    <timestamp>_<name_of_migration>_up.sql
+    <timestamp>_<name_of_migration>_down.sql
 
-    rake db:migrate:up VERSION=20081220234130
+    example: 20130128185251_foo_bar_migration_up.sql
+    example: 20130128185251_foo_bar_migration_down.sql
 
-### To revert your last migration
+These files are plain old SQL files and that's all they should contain.
 
-    rake db:rollback
+Using Ruby
 
-### To revert your last 3 migrations
+If you want to use the ActiveRecord domain-specific language to write your migrations instead of SQL, pass into the command the flag `type=ruby` so that the SQL scripts are not generated and then edit both the up and down methods of the file created in the `foo_bar_database/db/migrate` directory. The format of the filename is:
 
-    rake db:rollback STEP=3
+    <timestamp>_<name_of_migration>.rb
 
-### Custom configuration
+    example: 20130128185251_foo_bar_migration.rb
 
-By default, Standalone Migrations will assume there exists a "db/"
-directory in your project. But if for some reason you need a specific
-directory structure to work with, you can use a configuration file
-named .standalone_migrations in the root of your project containing
-the following:
+####Migrate database to latest version:
 
-```yaml
-db:
-    seeds: db/seeds.rb
-    migrate: db/migrate
-    schema: db/schema.rb
-config:
-    database: db/config.yml
-```
+    $ rake mule:migrate db=foo_bar_database
 
-These are the configurable options available. You can omit any of
-the keys and Standalone Migrations will assume the default values. 
+This command will run any migrations that have not been run on the database.
 
-#### Changing environment config in runtime
+####Migrate database to specific version (up or down depending on current version):
 
-If you are using Heroku or have to create or change your connection
-configuration based on runtime aspects (maybe environment variables),
-you can use the `StandaloneMigrations::Configurator.environments_config`
-method. Check the usage example:
+    $ rake mule:migrate db=foo_bar_database VERSION=<specific_version_number>
 
-```ruby
-require 'tasks/standalone_migrations'
+####Run a single, specific migration:
 
-StandaloneMigrations::Configurator.environments_config do |env|
+    $ rake mule:migrate:up db=foo_bar_database VERSION=<specific_version_number>
 
-  env.on "production" do
+    or
 
-    if (ENV['DATABASE_URL'])
-      db = URI.parse(ENV['DATABASE_URL'])
-      return {
-        :adapter  => db.scheme == 'postgres' ? 'postgresql' : db.scheme,
-        :host     => db.host,
-        :username => db.user,
-        :password => db.password,
-        :database => db.path[1..-1],
-        :encoding => 'utf8'
-      }
-    end
+    $ rake mule:migrate:down db=foo_bar_database VERSION=<specific_version_number>
 
-    nil
-  end
+####Rollback database to the previous version:
 
-end
-```
+    $ rake mule:rollback db=foo_bar_database
 
-You have to put this anywhere on your `Rakefile`. If you want to
-change some configuration, call the #on method on the object
-received as argument in your block passed to ::environments_config
-method call. The #on method receives the key to the configuration
-that you want to change within the block. The block should return
-your new configuration hash or nil if you want the configuration
-to stay the same.
+####Rollback database a certain number of steps:
 
-Your logic to decide the new configuration need to access some data
-in your current configuration? Then you should receive the configuration
-in your block, like this:
+    $ rake mule:rollback db=foo_bar_database STEP=<how_many_steps>
 
-```ruby
-require 'tasks/standalone_migrations'
+####Seed database:
 
-StandaloneMigrations::Configurator.environments_config do |env|
+    $ rake mule:seed db=foo_bar_database
 
-  env.on "my_custom_config" do |current_custom_config|
-    p current_custom_config
-    # => the values on your current "my_custom_config" environment
-    nil
-  end
+You can create arbitrary SQL files in the `foo_bar_database/db/seeds` directory and they will be executed with this command. Specify order by numbering your files. If you want the data to be removed at each call to `mule:seed`, then you need to add that logic.
 
-end
-```
+####Retrieve database version:
 
-#### Exporting Generated SQL
+    $ rake mule:version db=foo_bar_database
 
-If instead of the database-agnostic `schema.rb` file you'd like to
-save the database-specific SQL generated by the migrations, simply
-add this to your `Rakefile`.
+####Create database:
 
-```ruby
-require 'tasks/standalone_migrations'
-ActiveRecord::Base.schema_format = :sql
-```
+    $ rake mule:create db=foo_bar_database
+
+####Drop database:
+
+    $ rake mule:drop db=foo_bar_database
+
+####Reset database:
+
+    $ rake mule:reset db=foo_bar_database
+
+####Dump schema:
+
+    $ rake mule:structure:dump db=foo_bar_database
+
+####Load schema:
+
+    $ rake mule:structure:load db=foo_bar_database
+
+###Notes for production:
+
+####Database environment variables
+
+The `foo_bar_database/db/config.yml` file can contain environment variable accessors:
+
+    production:
+      adapter: postgresql
+      encoding: unicode
+      database: foo_bar_database_production
+      pool: 5
+      username: ENV['FOO_BAR_USER']
+      password: ENV['FOO_BAR_PSWD']
+      host: ENV['FOO_BAR_HOST']
+
+You can use this in production configurations to pass in database configuration during execution of the command:
+
+    $ rake mule:migrate db=foo_bar_database RAILS_ENV=production FOO_BAR_USER=<prod_user> FOO_BAR_PSWD=<prod_pswd> FOO_BAR_HOST=<prod_host>
+
+####Safeguard for destructive commands
+
+Mule has a safeguard system in place for any `foo_bar_database/db/config.yml` environment that contains the word 'production'. If you run any command that is typically destructive in nature (i.e. data could be lost), then it is required that you pass in an additional confirm argument to the command. The confirm argument must contain the database project name: 
 
-You should see a `db/structure.sql` file the next time you run a
-migration.
-
-Contributors
-============
- - [Todd Huss](http://gabrito.com/)
- - [Michael Grosser](http://pragmatig.wordpress.com)
- - [Ricardo Valeriano](http://ricardovaleriano.com/)
- - [Two Bit Labs](http://twobitlabs.com/)
- - [ClassMonkeys](http://www.classmonkeys.com/) 
- - [Windandtides](http://windandtides.com/)
- - [Eric Lindvall](http://bitmonkey.net)
- - [Steve Hodgkiss](http://stevehodgkiss.com/)
- - [Rich Meyers](https://github.com/richmeyers)
- - [Wes Bailey](http://exposinggotchas.blogspot.com/)
- - [Robert J. Berger](http://blog.ibd.com/)
- - [Federico Builes](http://mheroin.com/)
- - [Gazler](http://blog.gazler.com/)
- - [Yuu Yamashita](https://github.com/yyuu)
- - [Koen Punt](http://www.koen.pt/)
-
-This work is originally based on [Lincoln Stoll's blog post](http://lstoll.net/2008/04/stand-alone-activerecord-migrations/) and [David Welton's post](http://journal.dedasys.com/2007/01/28/using-migrations-outside-of-rails).
+    $ rake mule:rollback confirm=foo_bar_database db=foo_bar_database RAILS_ENV=production

data/Rakefile

@@ -31,7 +31,7 @@ rescue LoadError => e
 else
   Jeweler::Tasks.new do |gem|
     gem.name = 'dbmule'
-    gem.summary = "Mule is a database migration tool based upon a stand-alone version of Rails Migrations. It is customized to be used in environments with multiple existing databases and to use SQL scripts by default instead of Migrations DSL."
+    gem.summary = "Mule is a database migration tool based on a stand-alone version of Rails Migrations. By default, Mule uses SQL scripts instead of Migrations DSL, so no Ruby coding is required. It supports multi-database environments, including support for existing databases."
     gem.email = "willstepp@gmail.com"
     gem.homepage = "http://github.com/willstepp/dbmule"
     gem.authors = ["Daniel Stepp"]

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/dbmule.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "dbmule"
-  s.version = "0.1.0"
+  s.version = "0.1.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Daniel Stepp"]
-  s.date = "2013-01-28"
+  s.date = "2013-01-29"
   s.email = "willstepp@gmail.com"
   s.extra_rdoc_files = [
     "README.markdown"
@@ -39,7 +39,7 @@ Gem::Specification.new do |s|
   s.homepage = "http://github.com/willstepp/dbmule"
   s.require_paths = ["lib"]
   s.rubygems_version = "1.8.25"
-  s.summary = "Mule is a database migration tool based upon a stand-alone version of Rails Migrations. It is customized to be used in environments with multiple existing databases and to use SQL scripts by default instead of Migrations DSL."
+  s.summary = "Mule is a database migration tool based on a stand-alone version of Rails Migrations. By default, Mule uses SQL scripts instead of Migrations DSL, so no Ruby coding is required. It supports multi-database environments, including support for existing databases."
 
   if s.respond_to? :specification_version then
     s.specification_version = 3

data/lib/mule_migrations/tasks/mule.rake

@@ -18,7 +18,7 @@ development:
   pool: 5
   username:
   password:
-  host:
+  host: localhost
 
 test:
   adapter: postgresql
@@ -27,16 +27,16 @@ test:
   pool: 5
   username:
   password:
-  host:
+  host: localhost
 
 production:
   adapter: postgresql
   encoding: unicode
   database: #{db}_production
   pool: 5
-  username:
-  password:
-  host:
+  username: ENV['#{db.upcase}_USER']
+  password: ENV['#{db.upcase}_PSWD']
+  host: ENV['#{db.upcase}_HOST']
 eos
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dbmule
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-28 00:00:00.000000000 Z
+date: 2013-01-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -109,7 +109,8 @@ rubyforge_project:
 rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
-summary: Mule is a database migration tool based upon a stand-alone version of Rails
-  Migrations. It is customized to be used in environments with multiple existing databases
-  and to use SQL scripts by default instead of Migrations DSL.
+summary: Mule is a database migration tool based on a stand-alone version of Rails
+  Migrations. By default, Mule uses SQL scripts instead of Migrations DSL, so no Ruby
+  coding is required. It supports multi-database environments, including support for
+  existing databases.
 test_files: []