phil_columns 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fae5c938512a010ef32810b8a9a7e95d8a111e03
+  data.tar.gz: 560dd0e61b42b8300678346b1d1feeeeadfea172
+SHA512:
+  metadata.gz: 3b0d80f5f82ee4803f1188b47c24c48c7380abf132bceb30bd88bd86583a9669208cfe04fadebdbd9b25acd0e9ece1dcf227f03e3719d4bbb53c4c5b48de7996
+  data.tar.gz: 678cdb916e14ea29853b488a8ce4464ff9146b6cf8bd00958a2076c418376e0ca34adbb6bcf57e04f5a24d6bff36a58e1379dec4a69612ea8fadc051079103ce

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.ruby-gemset

@@ -0,0 +1 @@
+phil_columns

data/.ruby-version

@@ -0,0 +1 @@
+2.1.0

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.1.0

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in phil_columns.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 C. Jason Harrelson (midas)
+
+MIT License
+
+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,257 @@
+# PhilColumns
+
+A utility for seeding databases for development and production (works in Rails and non-Rails Ruby projects).
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'phil_columns'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install phil_columns
+
+To use all features of phil_columns you will need a database adapter. 
+
+    gem 'phil_columns-activerecord'
+
+Or
+
+    $ gem install phil_columns-activerecord
+
+
+## Usage
+
+### Installation into a project
+
+Installing phil_columns into a Ruby project.
+
+    $ phil_columns install some/path
+
+Installing phil_columns into a Rails project.
+
+    $ phil_columns install --rails
+
+The installation process puts in place the seeds directory and a configuration file: .phil_columns.  The --rails switch
+simply overrides some configurations to allow phil_columns to work in a Rails project.
+
+
+### Seeding Quick Start
+
+Use the generator to create a seed.
+
+    $ phil_columns generate seed add_things
+
+The generator puts a file in place.  Add your seeding logic to the #up and #down methods using any valid Ruby code.
+
+    # 20140513111454_add_things.rb.
+
+    class AddThings < PhilColumns::Seed
+      envs :development
+
+      def up
+        # seed logic ...
+      end
+
+      def down
+        # seed logic ...
+      end
+    end
+
+Execute the seed(s).
+
+    $ phil_columns seed
+
+
+### The Command Line Interface
+
+Get a summary of commands.
+
+    $ phil_columns help
+
+Get help with a command.
+
+    $ phil_columns help COMMAND
+    $ phil_columns help seed
+
+Some commands have sub-commands.  Get help witha sub-command.
+
+    $ phil_columns COMMAND help SUBCOMMAND
+    $ phil_columns generate help seed
+
+
+### The Seed Command
+
+The simplest usage of the seed command defaults the environment to 'development' and the version to 'all.'
+
+    $ phil_columns seed
+
+The environment can be overridden using the command line.  The environment is used to select only seeds that have been specified for the
+specified environment.
+
+    $ phil_columns seed --env production
+    $ phil_columns seed -e production
+
+The version can be overridden using the command line.  When a version is specified the seeding occurs up to the specified version.  When
+the seeding direction is up the version specified is included in the seeding set.  When seeding direction is down the specified version is 
+not included in the seed set.
+
+    $ phil_columns seed --version 20140513111454
+    $ phil_columns seed -v 20140513111454
+
+The direction of the seeding can be altered to down using the down switch.
+
+    $ phil_columns seed --down
+    $ phil_columns seed -d
+
+Finally, a dry run can be invoked using the dry-run switch.
+
+    $ phil_columns seed --dry-run
+
+
+### The Mulligan Command
+
+The mulligan command is a complete reset of the database.  The tables are removed and rebuilt and the data is seeded.  The strategy used to
+unload and load the schema is controlled by the configuration file attributes schema_unload\_strategy and schema\_load_strategy.  The mulligan 
+term is borrowed from golf where a mulligan is a do-over.
+
+The simplest usage of the mulligan command defaults the environment to 'development' and the version to 'all.'
+
+    $ phil_columns mulligan
+
+The environment can be overridden using the command line.  The environment is used to select only seeds that have been specified for the
+specified environment.
+
+    $ phil_columns mulligan --env production
+    $ phil_columns mulligan -e production
+
+The version can be overridden using the command line.  When a version is specified the seeding occurs up to the specified version.  When
+the seeding direction is up the version specified is included in the seeding set.  When seeding direction is down the specified version is 
+not included in the seed set.
+
+    $ phil_columns mulligan --version 20140513111454
+    $ phil_columns mulligan -v 20140513111454
+
+
+### The Empty Command
+
+The empty command empties all tables (excluding the schema_migrations table in a Rials project).
+
+The simplest usage of the empty command.
+
+    $ phil_columns empty
+
+
+### Additional Commands
+
+For documentation on additional commands/sub-commands use the command line interface's  built in help features.
+
+    $ phil_columns help
+    $ phil_columns help COMMAND
+    $ phil_columns COMMAND help
+    $ phil_columns COMMAND help SUBCOMMAND
+
+
+### Tags and Environments
+
+Tags and environments can be applied to seeds and filtered in command usage.  The seed generator adds the development environment by default and
+no tags.  This feature enables efficiency and adaptability in development seeding and the possibility to use phil_columns seeding in production 
+(see Production Seeding section below).
+
+Specifying environment(s) for a seed is accomplished with the ::envs class method.
+
+    class AddThings < PhilColumns::Seed
+      envs :development
+      ...
+    end
+
+To change the environment use the env switch.  When not specified the env defaults to development
+
+    $ phil_columns seed -e production
+
+Similary, applying tag(s) is accomplished using the ::tags class method.
+
+    class AddThings < PhilColumns::Seed
+      envs :development
+      tags :default
+      ...
+    end
+
+To change the tag(s) provide them after the command command line.  When not specified the tag(s) default to those provided in the default_tags 
+configuration attribute.
+
+    $ phil_columns seed defaults settings etc
+
+#### Advanced Filtering
+
+Currently, filtering is applied with the any operation, which is the default.  In the future development the all operation will be added and negation
+of tags.  For example:
+
+    $ phil_columns seed defaults ~settings --all
+
+
+
+### Production Seeding
+
+Systems often have system level data that must be seeded on initial startup and as new features or rolled out.  Some examples are settings, configurations,
+roles, licenses, etc.
+
+Phil_columns provides the ability to apply these system data seedings and commit them with features, analgous to a Rails migration.  The production seed file
+can be specified to run only in production, or in production and development if the data makes sense for both.
+
+To specify a seed for production, simply add production to the specified environments.
+
+    class AddThings < PhilColumns::Seed
+      envs :development, :production
+      ...
+    end
+
+
+### The Configuration File
+
+The configuration file is in YAML format.
+
+    ---
+    default_tags:
+    - default
+    env_files:
+    - config/environment
+    schema_load_strategy: load
+    schema_unload_strategy: drop
+    seeds_path: db/seeds
+
+#### Configuration Attributes
+
+##### default_tags
+
+[Array] A list of tags to apply when no tags are supplied to the command.  When empty, no tags are applied as default.  When not empty,
+one or more tags are applied as default.
+
+##### env_files
+
+[Array] A list of environment files to require.  Helps to set up environment before certain commands are executed.  You can provide your own, or utilize
+the environment file(s) from a framework, such as Rails.
+
+##### schema_load_strategy
+
+[String] The load strategy to use in commands that load the schema (ie. mulligan).  One of load or migrate.
+
+##### schema_unload_strategy
+
+[String] The unload strategy to use in commands that unload the schema (ie. mulligan).  One of drop or migrate.
+
+##### seeds_path
+
+[String] The relative path to the seeds directory.
+
+
+## Adapters and Extensions
+
+* [phil_columns-activerecord](https://github.com/midas/phil_columns-activerecord)
+* [phil_columns-factory_girl](https://github.com/midas/phil_columns-factory_girl)

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/phil_columns

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'phil_columns'
+
+PhilColumns::Cli.start

data/lib/phil_columns.rb

@@ -0,0 +1,27 @@
+require 'active_support/core_ext/string'
+require 'phil_columns/version'
+require 'phil_columns/railtie' if defined? Rails
+require 'rainbow'
+require 'pry-debugger'
+
+module PhilColumns
+
+  autoload :Archivist,     'phil_columns/archivist'
+  autoload :Cli,           'phil_columns/cli'
+  autoload :Command,       'phil_columns/command'
+  autoload :Configuration, 'phil_columns/configuration'
+  autoload :Error,         'phil_columns/error'
+  autoload :Filter,        'phil_columns/filter'
+  autoload :Migrator,      'phil_columns/migrator'
+  autoload :Output,        'phil_columns/output'
+  autoload :Seed,          'phil_columns/seed'
+  autoload :SeedUtils,     'phil_columns/seed_utils'
+  autoload :Seeder,        'phil_columns/seeder'
+  autoload :WithBackend,   'phil_columns/with_backend'
+
+  class << self
+    attr_accessor :archivist_klass
+    attr_accessor :migrator_klass
+  end
+
+end

data/lib/phil_columns/archivist.rb

@@ -0,0 +1,36 @@
+module PhilColumns
+  class Archivist
+
+    include PhilColumns::WithBackend
+
+    def initialize
+      @backend = PhilColumns::archivist_klass.new
+    end
+
+    def clear_seeds
+      raise( *error ) unless backend_responds?( :clear_seeds )
+      backend.send :clear_seeds
+    end
+
+    def record_seed( version )
+      raise( *error ) unless backend_responds?( :record_seed )
+      backend.send :record_seed, version
+    end
+
+    def remove_seed( version )
+      raise( *error ) unless backend_responds?( :remove_seed )
+      backend.send :remove_seed, version
+    end
+
+    def seed_already_executed?( version )
+      raise( *error ) unless backend_responds?( :seed_already_executed? )
+      backend.send :seed_already_executed?, version
+    end
+
+    def ensure_schema_seeds_table!
+      raise( *error ) unless backend_responds?( :ensure_schema_seeds_table! )
+      backend.send :ensure_schema_seeds_table!
+    end
+
+  end
+end

data/lib/phil_columns/cli.rb

@@ -0,0 +1,162 @@
+require 'thor'
+
+module PhilColumns
+  class Cli < Thor
+
+    autoload :Generate, 'phil_columns/cli/generate'
+    autoload :List,     'phil_columns/cli/list'
+
+    include Thor::Actions
+
+    def self.dry_run_option
+      option :dry_run, type: :boolean, desc: "When true, output steps but does not execute protected blocks"
+    end
+
+    def self.env_option
+      option :env, type: :string, aliases: '-e', desc: "The environment to execute in", default: 'development'
+    end
+
+    def self.env_option_description
+      %(When --env[-e] option, override the environment.  Default: development.)
+    end
+
+    def self.operation_option
+      option :operation, type: :string, aliases: '-o', desc: "The operation: all or any", default: 'any'
+    end
+
+    def self.operation_option_description
+      %(When --operation[-o] option, override the operation to one of any or all.  Default: any.)
+    end
+
+    def self.version_option
+      option :version, type: :string, aliases: '-v', desc: "The version to execute to", default: 'all'
+    end
+
+    def self.version_option_description
+      %(When --version[-v] option, override the version.  Default: all.  Provide the timestamp from the beginning of the seed file name
+      as the version parameter.  When seeding up, the specified version is included in the seed set.  When seeding down the specified
+      version is not included in the set.)
+    end
+
+    desc "empty", "Empty tables"
+    long_desc <<-LONGDESC
+      Empties all tables excluding any project metadata tables, ie. schema_migrations when using ActiveRecord.
+    LONGDESC
+    def empty( *tags )
+      execute PhilColumns::Command::Empty, tags: tags
+    end
+
+    desc 'generate SUBCOMMAND', "Generates different phil_columns assets"
+    subcommand "generate", PhilColumns::Cli::Generate
+
+    desc "install PATH", "Install phil_columns within a project"
+    long_desc <<-LONGDESC
+      Install phil_columns within a project at path PATH.
+
+      Installs a .phil_columns configuration file within PATH and a seeds directory at <PATH>/seeds by default.
+
+      When --rails[-r] option, install with defaults for a Rails project.  This includes the configuring the seeds directory
+      to db/seeds and adding config/enironment to the list of env_files in the configuration file.
+
+      When --seeds-path[-p] option, configure the seeds directory specified path.  This option is not necessary if --rails
+      option provided.
+    LONGDESC
+    option :rails, type: :boolean, aliases: '-r', desc: "When true, install with defaults for Rails"
+    option :seeds_path, type: :string, aliases: '-p', desc: "The path of the project to install within", default: './seeds'
+    def install( path='.' )
+      execute PhilColumns::Command::Install, path: path
+    end
+
+    desc 'list SUBCOMMAND', "List different seed info"
+    subcommand "list", PhilColumns::Cli::List
+
+    desc "mulligan [TAGS]", "Unload and load the schema then execute seeds"
+    long_desc <<-LONGDESC
+      A complete reset of the database.  The tables are removed and rebuilt and the data is seeded.  The strategy used to
+      unload and load the schema is controlled by the configuration file attributes schema_unload\_strategy and schema\_load_strategy.  The mulligan
+      term is borrowed from golf where a mulligan is a do-over.
+
+      #{env_option_description}
+
+      #{operation_option_description}
+
+      When --schema-load-strategy[-l] option, override the schema load strategy to one of load or migrate.  When load is specified loads
+      the schema.  When migrate specified runs the migrations.  Load is a more efficient operation.  Defaults to the value specified in
+      the configuration file attribute schema_load_strategy.
+
+      When --schema-unload-strategy[-l] option, override the schema unload strategy to one of drop or migrate.  When drop is specified drops
+      the tables.  When migrate specified runs the migrations down.  Drop is a more efficient operation.  Defaults to the value specified in
+      the configuration file attribute schema_unload_strategy.
+
+      #{version_option_description}
+    LONGDESC
+    env_option
+    operation_option
+    option :schema_load_strategy, type: :string, aliases: '-l', desc: "The schema load strategy to use: load or migrate"
+    option :schema_unload_strategy, type: :string, aliases: '-u', desc: "The schema unload strategy to use: drop or migrate"
+    version_option
+    def mulligan( *tags )
+      execute PhilColumns::Command::Mulligan, tags: tags
+    end
+
+    desc "seed [TAGS]", "Execute the seeds"
+    long_desc <<-LONGDESC
+      Execute the seeds.
+
+      When --down[-d] option, execute the down seeds.
+
+      When --dry-run option, execute the seeds as a dry run.
+
+      #{env_option_description}
+
+      #{operation_option_description}
+
+      #{version_option_description}
+    LONGDESC
+    option :down, type: :boolean, aliases: '-d', desc: "When true, executes down seeding"
+    dry_run_option
+    env_option
+    operation_option
+    version_option
+    def seed( *tags )
+      execute PhilColumns::Command::Seed, tags: tags
+    end
+
+    no_commands do
+
+      def execute( klass, additional_options={} )
+        klass.new( options.merge( additional_options )).execute
+      rescue PhilColumns::Error => e
+        handle_error( e )
+        exit 1
+      end
+
+      def handle_error( e )
+        say "Error: #{e.message}", :red
+      end
+
+    end
+
+    def self.handle_argument_error( command, error, _, __ )
+      method = "handle_argument_error_for_#{command.name}"
+
+      if respond_to?( method )
+        send( method, command, error )
+      else
+        handle_argument_error_default( command, error )
+      end
+    end
+
+    def self.handle_argument_error_default( command, error )
+      $stdout.puts "Incorrect usage of command: #{command.name}"
+      $stdout.puts "  #{error.message}", ''
+      $stdout.puts "For correct usage:"
+      $stdout.puts "  phil_columns help #{command.name}"
+    end
+
+    def self.handle_no_command_error( name )
+      $stdout.puts "Unrecognized command: #{name}"
+    end
+
+  end
+end