tmx_data_update 0.3.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2013 TMX Credit
+
+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,142 @@
+# TMX Data Update
+
+The problem of seed data can get annoying once your Rails app is in production.
+Ordinarily, you would place your seeds data in `seeds.rb`.  Unfortunately, once
+your application goes live, you will likely not be in a position to reload your
+seeds.  This leaves you with Rails migrations as the likely choice, but
+that now makes development harder, because things seed out of order (migrations
+run before seeds).  This gem solves these problems.
+
+## Installation
+
+In your Gemfile:
+
+```ruby
+gem 'tmx_data_update'
+```
+
+## Usage
+
+Data updates are defined similar to migrations.  Each file contains a class
+definition which should ideally extend `TmxDataUpdate::Updater` but doesn't have
+to as long as it implements `apply_update` and `revert_update`.  They need to
+follow the default Rails naming convention; a file called
+`update_order_types.rb` should contain the class `UpdateOrderTypes`.  It is
+highly recommended that each file have a prefix that defines its order.  The
+format is pretty flexible, but the prefix must start with a number and not have
+any underscores.  So `01_update_order_types.rb` is fine, so is
+`1A5_update_order_types.rb`.  In each of these cases, the name of the class is
+still `UpdateOrderTypes`.  If you extend `TmxDataUpdate::Updater` you only need to
+override `revert_update` if you need your migration to be reversible, otherwise
+it's not necessary.
+
+Here's an example data update class definition:
+
+```ruby
+class UpdateOrderTypes < TmxDataUpdates::Updater
+  def perform_update
+    OrderType.create :type_code => 'very_shiny'
+  end
+
+  # Overriden in case we need to roll back this migration.
+  def undo_update
+    OrderType.where(:type_code => 'very_shiny').first.delete
+  end
+end
+```
+
+### Migrations
+
+Assuming we have created the update file above in `db/data_updates` in a
+file named `01_update_order_types.rb`
+
+`root_updates_path` and  optionally `should_run?(update_name)` must be defined
+in every migration where we intend to do data updates.  Realistically, our app
+should extend `TmxDataUpdate` and then include the new module in each migration
+where needed.
+
+```ruby
+module CoreDataUpdate
+  include TmxDataUpdate
+
+  def root_updates_path
+    Rails.root.join('db','data_updates')
+  end
+
+  def should_run?(update_name)
+    Rails.env == 'production'
+  end
+end
+```
+
+Now, define a migration that will perform our data update.
+
+```ruby
+class CreateVeryShinyOrderType < ActiveRecord::Migration
+  include CoreDataUpdate
+
+  def up
+    apply_update :01_update_order_types
+  end
+
+  def down
+    revert_update :01_update_order_types
+  end
+end
+```
+
+Note that the update prefix is optional.  The following will also work.
+
+```ruby
+class CreateVeryShinyOrderType < ActiveRecord::Migration
+  include CoreDataUpdate
+
+  def up
+    apply_update :update_order_types
+  end
+
+  def down
+    revert_update :update_order_types
+  end
+end
+```
+
+Old style migrations, i.e. `def self.up` are not supported.
+
+### Seeds
+
+At the bottom of your `seeds.rb`, include the following:
+
+```ruby
+include TmxDataUpdate::Seeds
+apply_updates Rails.root.join('db','data_updates')
+```
+
+### Generators
+
+Two generators are added for your convenience:
+
+  * install: Updates the seeds file as specified above and creates a custom
+    data update module for engines. See
+    {file:lib/generators/tmx\_data\_update/create/USAGE} for examples
+  * create: Creates new data\_update and migration files as specified above. See
+    {file:lib/generators/tmx\_data\_update/install/USAGE} for examples
+
+NOTE: If you're using this from a Rails engine with Rails 3.2 and you're using
+RSpec to test, invoking the generator will likely put the generated files in
+`spec/dummy/db` instead of `db`.  Just something to be aware of.
+
+## Testing
+
+Install all the gem dependencies.
+
+    bundle install
+
+Run tests
+
+    rake spec
+
+## License
+
+Copyright (c) 2013 TMX Credit.
+Released under the MIT License.  See LICENSE file for details.

data/lib/generators/tmx_data_update/create/USAGE

@@ -0,0 +1,10 @@
+Description:
+  Creates files necessary for a data update
+
+Example:
+    rails generate tmx_data_update:create foo
+
+    This will:
+      * Create db/migrate/<timestamp>_foo.rb
+      * Create db/data_updates/<timestamp>_foo_data_update.rb
+        

data/lib/generators/tmx_data_update/create/create_generator.rb

@@ -0,0 +1,17 @@
+require 'rails/generators/active_record'
+require 'generators/tmx_data_update/helper'
+
+# Generator to create a data update + associated migration
+class TmxDataUpdate::CreateGenerator < Rails::Generators::NamedBase
+  include Generators::TmxDataUpdate::Helper
+  include Rails::Generators::Migration
+  extend ActiveRecord::Generators::Migration
+  
+  source_root File.expand_path('../templates', __FILE__)
+
+  # Creates the data update file and the migration file.
+  def create_helper_file
+    migration_template "data_update.rb", "db/data_updates/#{file_name}_data_update.rb"
+    migration_template "data_update_migration.rb", "db/migrate/#{file_name}.rb"
+  end
+end

data/lib/generators/tmx_data_update/create/templates/data_update.rb

@@ -0,0 +1,10 @@
+class <%= data_update_class_name %> < TmxDataUpdate::Updater
+  def perform_update
+    # <%= class_name %>.create :type_code => 'very_shiny'
+  end
+
+  # Overridden in case we need to roll back this migration.
+  def undo_update
+    # <%= class_name %>.where(:type_code => 'very_shiny').first.delete
+  end
+end

data/lib/generators/tmx_data_update/create/templates/data_update_migration.rb

@@ -0,0 +1,11 @@
+class <%= migration_class_name %> < ActiveRecord::Migration
+  include <%= application_class_name %>DataUpdate
+
+  def up
+    apply_update '<%= data_update_file_name  %>'
+  end
+
+  def down
+    revert_update '<%= data_update_file_name %>'
+  end
+end

data/lib/generators/tmx_data_update/helper.rb

@@ -0,0 +1,48 @@
+module Generators # :nodoc:
+  module TmxDataUpdate # :nodoc:
+    # Helper methods for generators
+    module Helper
+      # Is this a Rails Application or Engine?
+      # @return [Boolean]
+      def application?
+        Rails.application.is_a?(Rails::Application)
+      end
+
+      # Name of the application or engine useful for files and directories
+      # @return [String]
+      def application_name
+        if defined?(Rails) && Rails.application
+          application_class_name.underscore
+        else
+          "application"
+        end
+      end
+
+      # Fully qualified name of the application or engine
+      # @example AppName::Engine or AppName::Application
+      # @return [String]
+      def full_application_class_name
+        Rails.application.class.name
+      end
+
+      # Regular name of the application or engine
+      # @example AppName
+      # @return [String]
+      def application_class_name
+        full_application_class_name.split('::').first
+      end
+
+      # Class name for use in data_update files
+      # @return [String]
+      def data_update_class_name
+        migration_class_name
+      end
+
+      # Name useful for the data update file
+      # @return [String]
+      def data_update_file_name
+        "#{migration_number}_#{file_name}_data_update"
+      end
+    end
+  end
+end

data/lib/generators/tmx_data_update/install/USAGE

@@ -0,0 +1,11 @@
+Description:
+  Creates the necessary files to integrate with TmxDataUpdate
+
+Example:
+    rails generate tmx_data_update:install
+
+    This will:
+     * Update your db/seeds.rb to run the data update
+     * Add an initializer:
+        (Application) config/initializers/<application_name>_data_update.rb
+        (Engine) lib/<application_name>/<application_name>_data_update.rb

data/lib/generators/tmx_data_update/install/install_generator.rb

@@ -0,0 +1,33 @@
+require 'generators/tmx_data_update/helper'
+
+# Generator to install tmx data update in a new rails system.
+class TmxDataUpdate::InstallGenerator < Rails::Generators::Base
+  include Generators::TmxDataUpdate::Helper
+
+  source_root File.expand_path('../templates', __FILE__)
+
+  # Create the initializer file with default options.
+  def create_initializer
+    log :initializer, "Adding custom data update module"
+
+    if application?
+      template "data_update_module.rb", "config/initializers/#{application_name}_data_update.rb"
+    else
+      template "data_update_module.rb", "lib/#{application_name}/#{application_name}_data_update.rb"
+    end
+  end
+
+  # Update seeds.rb
+  def update_seeds
+    log :initializer, "Adding data update seeder to seeds.rb"
+
+    seed_code =<<SEED
+include TmxDataUpdate::Seeds
+apply_updates #{full_application_class_name}.root.join('db', 'data_updates')
+SEED
+
+    in_root do
+      inject_into_file 'db/seeds.rb', "\n#{seed_code}\n", { :before => /\z/, :verbose => false }
+    end
+  end
+end

data/lib/generators/tmx_data_update/install/templates/data_update_module.rb

@@ -0,0 +1,15 @@
+# Facilitates conducting data migrations.
+module <%= application_class_name %>DataUpdate
+  include TmxDataUpdate
+
+  # Returns the path where data updates are
+  def root_updates_path
+    <%= full_application_class_name %>.root.join('db','data_updates')
+  end
+
+  # Updates will run in production, but not in test an dev.
+  def should_run?(_)
+    Rails.env.production?
+  end
+
+end

data/lib/tmx_data_update/seeds.rb

@@ -0,0 +1,48 @@
+module TmxDataUpdate
+
+  # Should be included in seeds.rb to enable running data updates.
+  module Seeds
+    include UpdateClassLoader
+
+    # Applies all the updates from the given file system path.
+    #
+    # Basically, requires all the files from the given directory with a .rb
+    # suffix, instantiates the class in the file, and calls 'perform_update'
+    # on it.  This naturally requires that classes obey the default naming
+    # convention, i.e. a file named sample_update.rb should define a class
+    # named SampleUpdate.
+    #
+    # @param [String|Pathname|Symbol] updates_path
+    # @return [Hash] A hash or results; update => result
+    def apply_updates(updates_path)
+      update_files = get_update_files(updates_path)
+      results = {}
+      update_files.each { |file|
+        update = file.split('.').first
+        unless update.blank?
+          update_class = get_update_class(updates_path, update)
+          res = update_class.new.perform_update
+          results[update] = res
+        end
+      }
+      results
+    end
+
+    # Gets the list of what should be the update files from the given file
+    # system path, sorted in alphabetical order.  Returns an empty array if the
+    # updates_path is not on the file system or is not a directory.
+    # @param [String] updates_path
+    # @return [Array]
+    def get_update_files(updates_path)
+      if File.exists?(updates_path) && File.directory?(updates_path)
+        Dir.entries(updates_path).select { |file|
+          file.ends_with? '.rb'
+        }.sort
+      else
+        []
+      end
+    end
+    private :get_update_files
+
+  end
+end

data/lib/tmx_data_update/update_class_loader.rb

@@ -0,0 +1,57 @@
+module TmxDataUpdate
+  # Machinery to load the actual data update classes
+  module UpdateClassLoader
+
+    # Loads the class corresponding to the given update name from the given
+    #   file system path.
+    #
+    # @param [String|Pathname|Symbol] root_path
+    # @param [String|Symbol] update_name
+    #
+    # @return [::Class]
+    def get_update_class(root_path, update_name)
+      update = strip_seq_prefix(update_name.to_s)
+      file_name = find_file(root_path, update)
+      if file_name
+        file_name = File.basename(file_name, '.rb')
+        if root_path.to_s.ends_with?('/')
+          require "#{root_path}#{file_name}"
+        else
+          require "#{root_path}/#{file_name}"
+        end
+        update.camelize.constantize
+      else
+        raise LoadError, "Unable to find file for update #{update_name} in #{root_path}"
+      end
+    end
+
+    # Determines what's the actual filename for the given update name
+    def find_file(root_path, update)
+      update_file = "#{update}.rb"
+      Dir.entries(root_path).find{|entry| strip_seq_prefix(entry) == update_file }
+    end
+    private :find_file
+
+    # Takes the given file name and strips out the sequence prefix if any.  If
+    #   the file name starts with a digit, all characters up to the first '_' are
+    #   considered part of the prefix.  For example, for '00234ab_foo_bar' the
+    #   prefix would be '00234ab' and 'foo_bar' would be returned.
+    #
+    # @param [String] update_name
+    #
+    # @return [String]
+    def strip_seq_prefix(update_name)
+      index = update_name =~ /_/
+      if index
+        start = update_name[0,1]
+        # If the first letter of the prefix is a digit, we assume the prefix is
+        # for sequence ordering purposes.
+        if %w(0 1 2 3 4 5 6 7 8 9).include?(start)
+          update_name = update_name[index + 1, update_name.size - index]
+        end
+      end
+      update_name
+    end
+    private :strip_seq_prefix
+  end
+end

data/lib/tmx_data_update/updater.rb

@@ -0,0 +1,31 @@
+require 'active_record'
+
+
+module TmxDataUpdate
+
+  # Adds support for methods which are part of ActiveRecord::Migration interface.
+  # This is a convenience feature to make using data updates easier.
+  # The module should only implement methods relevant in the context of data
+  #   updates.
+  module ActiveRecordMigrationCompatible
+    delegate :execute, :to => ::ActiveRecord::Base
+  end
+
+  # The base class for all post-release data updates
+  #
+  # @abstract
+  class Updater
+    include ::TmxDataUpdate::ActiveRecordMigrationCompatible
+
+    # Performs the data update.  The subclass must override this method.
+    def perform_update
+      raise "#{self.class} should override 'update_data'"
+    end
+
+    # Reverses the update.  If the update is reversible, this class should
+    # be overriden in the subclass.
+    def undo_update
+      raise "#{self.class} does not support rolling back the update"
+    end
+  end
+end

data/lib/tmx_data_update.rb

@@ -0,0 +1,58 @@
+require 'active_support/all' # Should be required first.
+require 'tmx_data_update/update_class_loader' #Should be required second.
+
+require 'tmx_data_update/updater'
+require 'tmx_data_update/seeds'
+
+# Extends the migrations DSL to include the functionality to execute data updates.
+#
+# Note that each data update class is instantiated regardless of whether it is
+# expected to run. This enables the developer to discover any data update that
+# is incorrectly referenced in a migration, prior to deployment to production.
+module TmxDataUpdate
+  include TmxDataUpdate::UpdateClassLoader
+
+  # Returns the root data updates path.
+  def root_updates_path
+    raise "Must override in subclass!"
+  end
+
+  # Return +true+ if the named update should run, +false+ otherwise.  Subclasses
+  # are expected to override this as needed.
+  def should_run?(update_name)
+    true
+  end
+
+  # Applies the given update.
+  # @param [String|Symbol] update_name
+  def apply_update(update_name)
+    perform(update_name, :perform_update)
+  end
+
+  # Reverts the given update.
+  # @param [String|Symbol] update_name
+  def revert_update(update_name)
+    perform(update_name, :undo_update)
+  end
+
+  # Perform the update action.
+  # @param [String] update_name
+  # @param [Symbol] action Update action.
+  #         Either :perform_update or :undo_update
+  def perform(update_name, action)
+    update = load_updater_class(update_name)
+
+    update.send(action) if should_run?(update_name)
+  end
+  private :perform
+
+  # Load the updater class and instantiate it. This enables the developer
+  # to discover when the data update has been incorrectly referenced in the
+  # migration, prior to deployment to production.
+  # @param [String] update_name
+  def load_updater_class(update_name)
+    get_update_class(root_updates_path, update_name).new
+  end
+  private :load_updater_class
+
+end

metadata

@@ -0,0 +1,159 @@
+--- !ruby/object:Gem::Specification
+name: tmx_data_update
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+  prerelease: 
+platform: ruby
+authors:
+- Arthur Shagall
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-05-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ! 'Allows us to cleanly handle updates to seed data post-launch.
+
+'
+email: arthur.shagall@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE
+- README.md
+files:
+- lib/generators/tmx_data_update/create/USAGE
+- lib/generators/tmx_data_update/create/create_generator.rb
+- lib/generators/tmx_data_update/create/templates/data_update.rb
+- lib/generators/tmx_data_update/create/templates/data_update_migration.rb
+- lib/generators/tmx_data_update/helper.rb
+- lib/generators/tmx_data_update/install/USAGE
+- lib/generators/tmx_data_update/install/install_generator.rb
+- lib/generators/tmx_data_update/install/templates/data_update_module.rb
+- lib/tmx_data_update.rb
+- lib/tmx_data_update/seeds.rb
+- lib/tmx_data_update/update_class_loader.rb
+- lib/tmx_data_update/updater.rb
+- LICENSE
+- README.md
+homepage: http://www.tmxcredit.com
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Handle post-release data updates through migrations
+test_files: []
+has_rdoc: