planter 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5ec6b0fc5c0ec804e4a1ea2f1c050bcad9eadcc4cea08a8816a6b3ff17a1c37
-  data.tar.gz: 3639096bccfaf6aac225c78c7acfc919610802f4569fa239ffe4ffe7b648edcc
+  metadata.gz: 8b575630b7898231e26acae46bac6a745e46d9f60f596e3fe05af92adb6b36be
+  data.tar.gz: 3bac546364e78b3a9e84d40b29ead7ddf4b9453201ae4e9754f45227c6cf9963
 SHA512:
-  metadata.gz: 2da58e993a59e4019e83f9885826672158bf7483b7310ef07f86b54d93ceb3675bf7509c656a976372debac167aa2c12d6e12214d71be0acff253e0dd3d682b5
-  data.tar.gz: 80ce1e443cc6eafaf9eb1746f3d617fcf4b33bae7621d28e1f36a2a00a1f57a2e2638a2a629e02b0bdda049208b458a72e3bf43b4098d054e17f41ff8351d9de
+  metadata.gz: efe6a57b32e765863036c28eaad8c505812ee841aef607d39963f1430d6539c79c7942aa10f0014a711b92295150bc3a4bc41ff1343110e437f342f9137a4871
+  data.tar.gz: cae77c70d311dcbb8bb2618a7a14d06fcb393e6928f50cb378351ed81b972ddfa5250c9876633da398dac09af68f455793119884e164f829fc4064c6f5a50815

data/README.md

@@ -51,6 +51,7 @@ Planter.configure do |config|
   # The adapter used to create records, discover parent records, and
   # inspect database table names. Active Record is used by default.
   # To use a custom adapter, replace this line with your own adapter.
+  # The Active Record adapter can be configured with a block.
   config.adapter = Planter::Adapters::ActiveRecord.new
 
   ##
@@ -58,8 +59,8 @@ Planter.configure do |config|
   # config.seeders_directory, which can be changed below. When a new
   # seeder is generated, it will be appended to the bottom of this
   # list. If the order is incorrect, you'll need to adjust it.
-  # Just be sure to keep the ending bracket on its own line, or the
-  # generator won't know where to put new elements.
+  # The generator can append to either multiline or inline %i[...]
+  # arrays.
   config.seeders = %i[
   ]
 
@@ -75,6 +76,11 @@ Planter.configure do |config|
   # When true, don't print output when seeding.
   config.quiet = false
 
+  ##
+  # When false, don't print progress bars while seeding.
+  # This is ignored when config.quiet is true.
+  config.progress_bar = true
+
   ##
   # The default trim mode for ERB. Valid modes are:
   # '%'  enables Ruby code processing for lines beginning with %
@@ -209,6 +215,34 @@ test1@example.com,test1
 test2@example.com,test2
 ```
 
+By default, the Active Record adapter raises when model validations prevent a
+record from being created. To keep seeding after validation failures, configure
+the adapter to warn instead.
+
+```ruby
+Planter.configure do |config|
+  config.adapter = Planter::Adapters::ActiveRecord.new do |adapter_config|
+    adapter_config.validation_failure = :warn
+  end
+end
+```
+
+In `:warn` mode, Planter prints a warning with the failed lookup attributes and
+validation errors. This only applies to model-backed tables; model-less tables
+are inserted directly and can still raise database errors. A seeder can override
+the adapter default by defining `validation_failure`; Planter passes that value
+to adapters through `context.adapter_options`.
+
+```ruby
+class UsersSeeder < Planter::Seeder
+  seeding_method :csv, unique_columns: :email
+
+  def validation_failure
+    :raise
+  end
+end
+```
+
 CSV seeders can also be useful for simple model-less tables, such as join
 tables. With the default Active Record adapter, Planter will use the model when
 one exists and fall back to direct table inserts when one does not.
@@ -449,6 +483,10 @@ class MyAdapter
 end
 ```
 
+Planter passes adapter-specific per-seeder settings through
+`context.adapter_options`. Custom adapters can read options they support and
+ignore the rest.
+
 ## License
 The gem is available as open source under the terms of the [MIT
 License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -2,8 +2,13 @@ require "bundler/setup"
 require "bundler/gem_tasks"
 require "rake/testtask"
 require "rdoc/task"
+require "semverve/task"
 require "standard/rake"
 
+Semverve::Task.new do |t|
+  t.bundle_lock = true
+end
+
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.pattern = "test/**/*_test.rb"
@@ -17,48 +22,3 @@ RDoc::Task.new do |rdoc|
 end
 
 task default: :test
-
-namespace :version do
-  desc "Print the current version from the version.rb file"
-  task :current do
-    puts Planter::VERSION
-  end
-
-  namespace :increment do
-    desc "Increment the version's PATCH level"
-    task :patch do
-      File.join(__dir__, "lib", "planter", "version.rb").then do |version_file|
-        File.write(
-          version_file,
-          File.read(version_file).sub(/(PATCH\s=\s)(\d+)/) { "#{$1}#{$2.next}" }
-        )
-      end
-      system("bundle lock")
-    end
-    desc "Increment the version's MINOR level"
-    task :minor do
-      File.join(__dir__, "lib", "planter", "version.rb").then do |version_file|
-        File.write(
-          version_file,
-          File.read(version_file)
-            .sub(/(PATCH\s=\s)(\d+)/) { "#{$1}0" }
-            .sub(/(MINOR\s=\s)(\d+)/) { "#{$1}#{$2.next}" }
-        )
-      end
-      system("bundle lock")
-    end
-    desc "Increment the version's MAJOR level"
-    task :major do
-      File.join(__dir__, "lib", "planter", "version.rb").then do |version_file|
-        File.write(
-          version_file,
-          File.read(version_file)
-            .sub(/(PATCH\s=\s)(\d+)/) { "#{$1}0" }
-            .sub(/(MINOR\s=\s)(\d+)/) { "#{$1}0" }
-            .sub(/(MAJOR\s=\s)(\d+)/) { "#{$1}#{$2.next}" }
-        )
-      end
-      system("bundle lock")
-    end
-  end
-end

data/lib/generators/planter/initializer_generator.rb

@@ -19,6 +19,7 @@ module Planter
             # The adapter used to create records, discover parent records, and
             # inspect database table names. Active Record is used by default.
             # To use a custom adapter, replace this line with your own adapter.
+            # The Active Record adapter can be configured with a block.
             config.adapter = Planter::Adapters::ActiveRecord.new
 
             ##
@@ -26,8 +27,8 @@ module Planter
             # config.seeders_directory, which can be changed below. When a new
             # seeder is generated, it will be appended to the bottom of this
             # list. If the order is incorrect, you'll need to adjust it.
-            # Just be sure to keep the ending bracket on its own line, or the
-            # generator won't know where to put new elements.
+            # The generator can append to either multiline or inline %i[...]
+            # arrays.
             config.seeders = %i[
             ]
 
@@ -43,6 +44,11 @@ module Planter
             # When true, don't print output when seeding.
             config.quiet = false
 
+            ##
+            # When false, don't print progress bars while seeding.
+            # This is ignored when config.quiet is true.
+            config.progress_bar = true
+
             ##
             # The default trim mode for ERB. Valid modes are:
             # '%'  enables Ruby code processing for lines beginning with %

data/lib/planter/adapters/active_record.rb

@@ -22,6 +22,57 @@ module Planter
     # resolving those values into whatever persistence or reflection objects
     # they need.
     class ActiveRecord
+      ##
+      # Validation failure actions supported by the Active Record adapter.
+      #
+      # @return [Array<Symbol>]
+      VALIDATION_FAILURE_ACTIONS = %i[raise warn].freeze
+
+      ##
+      # Configuration for the Active Record adapter.
+      class Configuration
+        ##
+        # How model validation failures should be handled when creating records.
+        #
+        # @return [Symbol]
+        attr_reader :validation_failure
+
+        ##
+        # Create a new Active Record adapter configuration.
+        def initialize
+          @validation_failure = :raise
+        end
+
+        ##
+        # Set how model validation failures should be handled.
+        #
+        # @param [String, Symbol] action either +:raise+ or +:warn+
+        def validation_failure=(action)
+          action = action.to_sym
+          unless VALIDATION_FAILURE_ACTIONS.include?(action)
+            raise ArgumentError, "validation_failure must be: #{VALIDATION_FAILURE_ACTIONS.join(", ")}"
+          end
+
+          @validation_failure = action
+        end
+      end
+
+      ##
+      # The adapter configuration.
+      #
+      # @return [Planter::Adapters::ActiveRecord::Configuration]
+      attr_reader :configuration
+
+      ##
+      # Create a new Active Record adapter.
+      #
+      # @yield [configuration] optional configuration block
+      # @yieldparam configuration [Planter::Adapters::ActiveRecord::Configuration]
+      def initialize
+        @configuration = Configuration.new
+        yield configuration if block_given?
+      end
+
       ##
       # Create a record unless one already exists.
       #
@@ -35,9 +86,7 @@ module Planter
       # @return [Object]
       def create_record(context:, lookup_attributes:, create_attributes:)
         if (model = model(context))
-          model
-            .where(lookup_attributes)
-            .first_or_create!(create_attributes)
+          create_model_record(model, context, lookup_attributes, create_attributes)
         else
           create_table_record(context, lookup_attributes, create_attributes)
         end
@@ -99,6 +148,48 @@ module Planter
         end
       end
 
+      def create_model_record(model, context, lookup_attributes, create_attributes)
+        relation = model.where(lookup_attributes)
+        case validation_failure(context)
+        when :raise
+          relation.first_or_create!(create_attributes)
+        when :warn
+          record = relation.first_or_create(create_attributes)
+          warn_validation_failure(context, lookup_attributes, record) if failed_create?(record)
+          record
+        end
+      end
+
+      def validation_failure(context)
+        adapter_options = context.adapter_options if context.respond_to?(:adapter_options)
+        context_action = adapter_options&.[](:validation_failure)
+        action = context_action || configuration.validation_failure
+        action = action.to_sym
+        return action if VALIDATION_FAILURE_ACTIONS.include?(action)
+
+        raise ArgumentError, "validation_failure must be: #{VALIDATION_FAILURE_ACTIONS.join(", ")}"
+      end
+
+      def failed_create?(record)
+        record == false || (record.respond_to?(:persisted?) && !record.persisted?)
+      end
+
+      def warn_validation_failure(context, lookup_attributes, record)
+        warn(
+          [
+            "WARNING: Planter could not create #{context.table_name} with lookup attributes",
+            lookup_attributes.inspect,
+            validation_errors(record)
+          ].compact.join(" ")
+        )
+      end
+
+      def validation_errors(record)
+        return unless record.respond_to?(:errors) && record.errors.any?
+
+        "Errors: #{record.errors.full_messages.join(", ")}"
+      end
+
       def association_options(context)
         model!(context).reflect_on_association(context.parent).options
       end

data/lib/planter/config.rb

@@ -42,6 +42,14 @@ module Planter
     # @return [Boolean]
     attr_accessor :quiet
 
+    ##
+    # When false, don't print progress bars while seeding.
+    #
+    # @param [Boolean] progress_bar
+    #
+    # @return [Boolean]
+    attr_accessor :progress_bar
+
     ##
     # The default trim mode for ERB. Must be "%", "<>", ">", or "-".
     # For more information, see documentation for +ERB::new+.
@@ -72,6 +80,7 @@ module Planter
     # Create a new instance of the config.
     def initialize
       @quiet = false
+      @progress_bar = true
       @seeders_directory = ::File.join("db", "seeds")
       @csv_files_directory = ::File.join("db", "seed_files")
     end

data/lib/planter/progress_bar.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "ruby-progressbar"
+
+module Planter
+  ##
+  # Builds progress bars for seed runs.
+  class ProgressBar
+    ##
+    # The format string used by visible progress bars.
+    #
+    # @return [String]
+    FORMAT = "%t |%B| %p%% %c/%C"
+
+    ##
+    # Progress bar object used when visible progress bars are disabled.
+    class NullProgressBar
+      ##
+      # No-op progress increment.
+      def increment
+      end
+    end
+
+    ##
+    # Create a visible progress bar, or a null progress bar when disabled.
+    #
+    # @param [String] title progress bar title
+    # @param [Integer] total total number of records to seed
+    # @param [IO] output progress bar output stream
+    #
+    # @return [ProgressBar, NullProgressBar]
+    def self.create(title:, total:, output: $stdout)
+      return NullProgressBar.new unless enabled?(total)
+
+      ::ProgressBar.create(
+        title: title,
+        total: total,
+        output: output,
+        format: FORMAT
+      )
+    end
+
+    def self.enabled?(total)
+      total.positive? && Planter.config.progress_bar && !Planter.config.quiet
+    end
+    private_class_method :enabled?
+  end
+end

data/lib/planter/seed_context.rb

@@ -46,6 +46,14 @@ module Planter
     # @return [String, nil]
     attr_reader :erb_trim_mode
 
+    ##
+    # Adapter-specific options collected from the seeder.
+    #
+    # Adapters may ignore any options they do not support.
+    #
+    # @return [Hash]
+    attr_reader :adapter_options
+
     ##
     # Create a new seed context.
     #
@@ -62,6 +70,8 @@ module Planter
     # @param [Array<Symbol>, nil] unique_columns
     #
     # @param [String, nil] erb_trim_mode
+    #
+    # @param [Hash] adapter_options adapter-specific per-seeder options
     def initialize(
       table_name:,
       seed_method:,
@@ -69,7 +79,8 @@ module Planter
       parent:,
       number_of_records:,
       unique_columns:,
-      erb_trim_mode:
+      erb_trim_mode:,
+      adapter_options: {}
     )
       @table_name = table_name.to_s
       @seed_method = seed_method&.intern
@@ -78,6 +89,7 @@ module Planter
       @number_of_records = number_of_records
       @unique_columns = unique_columns
       @erb_trim_mode = erb_trim_mode
+      @adapter_options = adapter_options.to_h.transform_keys(&:to_sym)
     end
   end
 end

data/lib/planter/seeder.rb

@@ -89,6 +89,11 @@ module Planter
   #
   # If you need to seed a different way, put your own custom +seed+ method in
   # your seeder class and do whatever needs to be done.
+  #
+  # Adapter-specific settings can be provided by defining methods on your
+  # seeder. For example, the Active Record adapter reads +validation_failure+
+  # into +SeedContext#adapter_options+ when deciding whether failed model
+  # validations should raise or warn.
   class Seeder
     ##
     # The allowed seeding methods.
@@ -261,17 +266,35 @@ module Planter
     ##
     # Creates records from the +data+ attribute.
     def create_records
-      context.number_of_records.times do
-        data.each { |record| create_record(record) }
+      records = data
+      progress_bar = progress_bar(total: context.number_of_records * records.size)
+
+      context.number_of_records.times do |index|
+        records = data if index.positive?
+        records.each do |record|
+          create_record(record)
+          progress_bar.increment
+        end
       end
     end
 
     ##
     # Create records from the +data+ attribute for each record in the +parent+.
     def create_records_from_parent
-      adapter.parent_ids(context: context).each do |parent_id|
-        context.number_of_records.times do
-          data.each { |record| create_record(record, parent_id: parent_id) }
+      parent_ids = adapter.parent_ids(context: context)
+      return if parent_ids.empty?
+
+      records = data
+      total = parent_ids.size * context.number_of_records * records.size
+      progress_bar = progress_bar(total: total)
+
+      parent_ids.each_with_index do |parent_id, parent_index|
+        context.number_of_records.times do |number_index|
+          records = data if parent_index.positive? || number_index.positive?
+          records.each do |record|
+            create_record(record, parent_id: parent_id)
+            progress_bar.increment
+          end
         end
       end
     end
@@ -308,10 +331,21 @@ module Planter
         parent: parent,
         number_of_records: number_of_records,
         unique_columns: unique_columns,
-        erb_trim_mode: erb_trim_mode
+        erb_trim_mode: erb_trim_mode,
+        adapter_options: seeder_adapter_options
       )
     end
 
+    def seeder_adapter_options
+      {
+        validation_failure: seeder_validation_failure
+      }.compact
+    end
+
+    def seeder_validation_failure
+      public_send(:validation_failure) if respond_to?(:validation_failure)
+    end
+
     def csv_data_source
       @csv_data_source ||= Planter::CsvDataSource.new(context: context, seeder: self)
     end
@@ -327,5 +361,9 @@ module Planter
     def adapter
       Planter.config.adapter
     end
+
+    def progress_bar(total:)
+      Planter::ProgressBar.create(title: context.table_name, total: total)
+    end
   end
 end

data/lib/planter/version.rb

@@ -15,13 +15,13 @@ module Planter
     # Minor version.
     #
     # @return [Integer]
-    MINOR = 0
+    MINOR = 1
 
     ##
     # Patch version.
     #
     # @return [Integer]
-    PATCH = 1
+    PATCH = 0
 
     module_function
 

data/lib/planter.rb

@@ -7,6 +7,7 @@ require "planter/railtie"
 require "planter/config"
 require "planter/seed_context"
 require "planter/csv_data_source"
+require "planter/progress_bar"
 require "planter/record_attributes"
 require "planter/seeder"
 require "planter/validator"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: planter
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Evan Gray
@@ -43,6 +43,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: ruby-progressbar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
 - !ruby/object:Gem::Dependency
   name: parallel
   requirement: !ruby/object:Gem::Requirement
@@ -57,6 +71,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: semverve
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -103,6 +131,7 @@ files:
 - lib/planter/adapters/active_record.rb
 - lib/planter/config.rb
 - lib/planter/csv_data_source.rb
+- lib/planter/progress_bar.rb
 - lib/planter/railtie.rb
 - lib/planter/record_attributes.rb
 - lib/planter/seed_context.rb