planter 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbae89995fbeb940ff4ddb50b0f8a498963d84a2a7666d9d6542786c912fb455
-  data.tar.gz: d2e4e7c56c11b5ce5439baf13df756ad506d0ac50089334e8fa2ebea39a9c757
+  metadata.gz: 48ca5902ca8e033fca09dedeed1c7f62efbffc3a347149787b7282030045c740
+  data.tar.gz: b79c752f9db2e5ab8b7067a0a7c41066e4ad731d7090f861eb38cfd5d73ef8cc
 SHA512:
-  metadata.gz: 412a63aad94073f9140d57b9271c3900392a6f528431ce54b1a9c2303b3fa1c1553a00b1a5e2d8b0f221b9c6d328ab95720d451b2224e44a24216808522636e3
-  data.tar.gz: 73edbbebe39d0759c053eee8f09d2b3ea0267b7533aa720b563faaddc9582be7bec451c87221404bd8b2d58f163d12f12257694cf28203c7e6b4121b3353567a
+  metadata.gz: 9db7c6dc7a76a834aa21a69423f4e3bf97d637eee7169c32ec75dc773dfda69a622510ba947c969691ab894d4ed9d098222653273caae06e0e00424d9a166df3
+  data.tar.gz: 6923ec3963d9b6af5c48bc2deb418ab2d9885814e97243501269eb0b6379376457e2dddbc23bd907d00ed75362441bd40563de5349bf71957259ca87244beb34

data/README.md

@@ -23,7 +23,7 @@ currently a pre-release version, it's recommended to lock it to a specific
 version, as breaking changes may occur, even at the minor level.
 
 ```ruby
-gem 'planter', '0.3.2'
+gem 'planter', '0.4.0'
 ```
 
 And then execute:
@@ -46,8 +46,15 @@ To get started, run `rails generate planter:initializer`, which will create
 
 ```ruby
 require 'planter'
+require 'planter/adapters/active_record'
 
 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.
+  config.adapter = Planter::Adapters::ActiveRecord.new
+
   ##
   # The list of seeders. These files are stored in the
   # config.seeders_directory, which can be changed below. When a new
@@ -114,7 +121,12 @@ the generator won't know where to put the new seeders.
 If you want to generate a seeder for every table currently in your database, run
 `rails generate planter:seeder ALL`.
 
-You then need to choose a seeding method, of which there are currently three.
+Planter uses `Planter::Adapters::ActiveRecord` by default, so the built-in
+seeding methods work with Active Record models without extra configuration. See
+[Custom Adapters](#custom-adapters) if you want to use a different persistence
+backend.
+
+You then need to choose a seeding method, of which there are currently two.
 
 ### Seeding from CSV
 To seed from CSV, you simply need to add the following to your seeder class.
@@ -251,9 +263,9 @@ Running `rails planter:seed` should now seed your `users` table.
 You can also seed children records for every existing record of a parent model.
 For example, to seed an address for every user, you'd need to create an
 `AddressesSeeder` that uses the `parent` option, as seen below. This option
-should be the name of the `belongs_to` association in your model. The primary
-key, foreign key, and model name of the parent will all be determined by
-reflecting on the association.
+should be the name of the `belongs_to` association in your model when using the
+default Active Record adapter. The primary key, foreign key, and model name of
+the parent will all be determined by the adapter.
 
 ```ruby
 require 'faker'
@@ -292,6 +304,56 @@ class UsersSeeder < Planter::Seeder
 end
 ```
 
+## Custom Adapters
+Active Record is the default adapter, but you can provide your own adapter
+object in the initializer. Replace the generated Active Record adapter require
+and configuration with your custom adapter, while keeping `config.seeders` as
+your ordered seed plan.
+
+You can generate a custom adapter stub with the following command.
+
+```bash
+$ rails generate planter:adapter sequel
+```
+
+This creates `lib/planter/adapters/sequel.rb` with the required adapter methods
+and updates `config/initializers/planter.rb` to use it. The generated methods
+raise `NotImplementedError` until you implement them. Running the generator
+replaces the currently configured adapter line, but does not change
+`config.seeders`.
+
+```ruby
+require 'planter'
+require 'my_adapter'
+
+Planter.configure do |config|
+  config.adapter = MyAdapter.new
+end
+```
+
+Custom adapters are duck typed. They should implement the same public API as
+`Planter::Adapters::ActiveRecord`.
+
+```ruby
+class MyAdapter
+  def create_record(model_name:, lookup_attributes:, create_attributes:)
+    # Find or create a record for model_name.
+  end
+
+  def parent_ids(model_name:, parent:)
+    # Return ids for each parent record used by parent seeding.
+  end
+
+  def foreign_key(model_name:, parent:)
+    # Return the attribute used to attach a parent id to the seeded record.
+  end
+
+  def table_names
+    # Return table or collection names used by `rails generate planter:seeder ALL`.
+  end
+end
+```
+
 ## License
 The gem is available as open source under the terms of the [MIT
 License](https://opensource.org/licenses/MIT).

data/lib/generators/planter/adapter_generator.rb

@@ -0,0 +1,140 @@
+module Planter
+  module Generators
+    class AdapterGenerator < Rails::Generators::Base
+      argument :adapter, required: true
+
+      desc "Creates an adapter file at lib/planter/adapters"
+
+      def generate_adapter
+        create_file adapter_path, <<~RUBY
+          # frozen_string_literal: true
+
+          module Planter
+            module Adapters
+              ##
+              # Custom adapter for Planter.
+              class #{adapter_class_name}
+                ##
+                # Create a record unless one already exists.
+                #
+                # @param [String] model_name the model being seeded
+                #
+                # @param [Hash] lookup_attributes attributes used to find the record
+                #
+                # @param [Hash] create_attributes additional attributes used only when
+                #   creating a new record
+                #
+                # @return [Object]
+                def create_record(model_name:, lookup_attributes:, create_attributes:)
+                  raise NotImplementedError, "\#{self.class} must implement #create_record"
+                end
+
+                ##
+                # Return the parent ids to use when seeding child records.
+                #
+                # @param [String] model_name the model being seeded
+                #
+                # @param [String, Symbol] parent the parent association name
+                #
+                # @return [Array]
+                def parent_ids(model_name:, parent:)
+                  raise NotImplementedError, "\#{self.class} must implement #parent_ids"
+                end
+
+                ##
+                # Return the foreign key used to assign a parent id on a child record.
+                #
+                # @param [String] model_name the model being seeded
+                #
+                # @param [String, Symbol] parent the parent association name
+                #
+                # @return [String, Symbol]
+                def foreign_key(model_name:, parent:)
+                  raise NotImplementedError, "\#{self.class} must implement #foreign_key"
+                end
+
+                ##
+                # Return table or collection names that can have seeders generated.
+                #
+                # @return [Array<String>]
+                def table_names
+                  raise NotImplementedError, "\#{self.class} must implement #table_names"
+                end
+              end
+            end
+          end
+        RUBY
+      end
+
+      def update_initializer
+        contents = ::File.read(initializer_full_path)
+        contents = replace_or_insert_adapter_require(contents)
+        contents = replace_or_insert_adapter_config(contents)
+
+        ::File.write(initializer_full_path, contents)
+      end
+
+      private
+
+      def adapter_path
+        "lib/planter/adapters/#{adapter_file_name}.rb"
+      end
+
+      def adapter_file_name
+        adapter.underscore
+      end
+
+      def adapter_class_name
+        adapter.camelize
+      end
+
+      def adapter_require_line
+        "require Rails.root.join('lib/planter/adapters/#{adapter_file_name}').to_s"
+      end
+
+      def adapter_config_line
+        "config.adapter = Planter::Adapters::#{adapter_class_name}.new"
+      end
+
+      def initializer_path
+        "config/initializers/planter.rb"
+      end
+
+      def initializer_full_path
+        ::File.join(destination_root, initializer_path)
+      end
+
+      def replace_or_insert_adapter_require(contents)
+        if contents.match?(adapter_require_pattern)
+          contents.sub(adapter_require_pattern, adapter_require_line)
+        else
+          contents.sub(planter_require_pattern) { |line| "#{line.chomp}\n#{adapter_require_line}\n" }
+        end
+      end
+
+      def replace_or_insert_adapter_config(contents)
+        if contents.match?(adapter_config_pattern)
+          contents.sub(adapter_config_pattern) { "#{$1}#{adapter_config_line}" }
+        else
+          contents.sub(configure_pattern) { |line| "#{line}\n#{$1}  #{adapter_config_line}" }
+        end
+      end
+
+      def adapter_require_pattern
+        /^[ \t]*require ["']planter\/adapters\/[^"']+["'][ \t]*$/
+      end
+
+      def planter_require_pattern
+        /^[ \t]*require ["']planter["'][ \t]*\n?/
+      end
+
+      def adapter_config_pattern
+        /^([ \t]*)config\.adapter\s*=.*$/
+      end
+
+      def configure_pattern
+        /^([ \t]*)Planter\.configure do \|config\|[ \t]*$/
+      end
+    end
+  end
+end

data/lib/generators/planter/initializer_generator.rb

@@ -6,8 +6,15 @@ module Planter
       def create_initializer_file
         create_file "config/initializers/planter.rb", <<~EOF
           require 'planter'
+          require 'planter/adapters/active_record'
 
           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.
+            config.adapter = Planter::Adapters::ActiveRecord.new
+
             ##
             # The list of seeders. These files are stored in the
             # config.seeders_directory, which can be changed below. When a new

data/lib/generators/planter/seeder_generator.rb

@@ -31,9 +31,7 @@ module Planter
       end
 
       def tables
-        @tables ||= ActiveRecord::Base.connection.tables.reject do |table|
-          %w[ar_internal_metadata schema_migrations].include?(table)
-        end
+        @tables ||= ::Planter.config.adapter.table_names
       end
     end
   end

data/lib/planter/adapters/active_record.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Planter
+  module Adapters
+    ##
+    # Default adapter for seeding Active Record models.
+    #
+    # Custom adapters should implement this public API:
+    # - +create_record(model_name:, lookup_attributes:, create_attributes:)+
+    # - +parent_ids(model_name:, parent:)+
+    # - +foreign_key(model_name:, parent:)+
+    # - +table_names+
+    #
+    # +model_name+ is the configured seeder model name. +parent+ is the
+    # configured parent association name. Adapters are responsible for resolving
+    # those values into whatever persistence or reflection objects they need.
+    class ActiveRecord
+      ##
+      # Create a record unless one already exists.
+      #
+      # @param [String] model_name the model being seeded
+      #
+      # @param [Hash] lookup_attributes attributes used to find the record
+      #
+      # @param [Hash] create_attributes additional attributes used only when
+      #   creating a new record
+      #
+      # @return [Object]
+      def create_record(model_name:, lookup_attributes:, create_attributes:)
+        model_name.constantize
+          .where(lookup_attributes)
+          .first_or_create!(create_attributes)
+      end
+
+      ##
+      # Return the parent ids to use when seeding child records.
+      #
+      # @param [String] model_name the model being seeded
+      #
+      # @param [String, Symbol] parent the parent association name
+      #
+      # @return [Array]
+      def parent_ids(model_name:, parent:)
+        parent_model(model_name, parent).constantize.pluck(primary_key(model_name, parent))
+      end
+
+      ##
+      # Return the foreign key used to assign a parent id on a child record.
+      #
+      # @param [String] model_name the model being seeded
+      #
+      # @param [String, Symbol] parent the parent association name
+      #
+      # @return [String, Symbol]
+      def foreign_key(model_name:, parent:)
+        association_options(model_name, parent).fetch(:foreign_key, "#{parent}_id")
+      end
+
+      ##
+      # Return application table names that can have seeders generated.
+      #
+      # @return [Array<String>]
+      def table_names
+        ::ActiveRecord::Base.connection.tables.reject do |table|
+          %w[ar_internal_metadata schema_migrations].include?(table)
+        end
+      end
+
+      private
+
+      def association_options(model_name, parent)
+        model_name.constantize.reflect_on_association(parent).options
+      end
+
+      def primary_key(model_name, parent)
+        association_options(model_name, parent).fetch(:primary_key, :id)
+      end
+
+      def parent_model(model_name, parent)
+        association_options(model_name, parent).fetch(:class_name, parent.to_s.classify)
+      end
+    end
+  end
+end

data/lib/planter/config.rb

@@ -51,6 +51,23 @@ module Planter
     # @return [String]
     attr_accessor :erb_trim_mode
 
+    ##
+    # The adapter used to create records, discover parent records, and inspect
+    # database table names. Custom adapters should implement the public API
+    # documented by +Planter::Adapters::ActiveRecord+.
+    #
+    # @return [Object]
+    attr_writer :adapter
+
+    ##
+    # Return the configured adapter, or lazily load the default Active Record
+    # adapter.
+    #
+    # @return [Object]
+    def adapter
+      @adapter ||= default_adapter
+    end
+
     ##
     # Create a new instance of the config.
     def initialize
@@ -58,5 +75,13 @@ module Planter
       @seeders_directory = ::File.join("db", "seeds")
       @csv_files_directory = ::File.join("db", "seed_files")
     end
+
+    private
+
+    def default_adapter
+      require "planter/adapters/active_record"
+
+      Planter::Adapters::ActiveRecord.new
+    end
   end
 end

data/lib/planter/seeder.rb

@@ -258,7 +258,7 @@ module Planter
     ##
     # Create records from the +data+ attribute for each record in the +parent+.
     def create_records_from_parent
-      parent_model.constantize.pluck(primary_key).each do |parent_id|
+      adapter.parent_ids(model_name: model, parent: parent).each do |parent_id|
         number_of_records.times do
           data.each { |record| create_record(record, parent_id: parent_id) }
         end
@@ -267,13 +267,36 @@ module Planter
 
     def create_record(record, parent_id: nil)
       unique, attrs = split_record(apply_transformations(record))
-      model.constantize.where(
-        unique.tap { |u| u[foreign_key] = parent_id if parent_id }
-      ).first_or_create!(attrs)
+      unique = unique.merge(foreign_key => parent_id) if parent_id
+      adapter.create_record(
+        model_name: model,
+        lookup_attributes: unique,
+        create_attributes: attrs
+      )
+    end
+
+    def full_csv_name
+      @full_csv_name ||=
+        %W[#{csv_name}.csv #{csv_name}.csv.erb #{csv_name}.erb.csv]
+          .map { |f| Rails.root.join(Planter.config.csv_files_directory, f).to_s }
+          .find { |f| ::File.file?(f) }
+    end
+
+    def extract_data_from_csv
+      contents = ::File.read(full_csv_name)
+      if full_csv_name.include?(".erb")
+        contents = ERB.new(contents, trim_mode: erb_trim_mode).result(binding)
+      end
+
+      @data ||= ::CSV.parse(
+        contents,
+        headers: true,
+        header_converters: :symbol
+      ).map(&:to_hash)
     end
 
     def validate_attributes # :nodoc:
-      case seed_method.intern
+      case seed_method&.intern
       when :csv
         raise "Couldn't find csv for #{model}" unless full_csv_name
       when :data_array
@@ -311,44 +334,12 @@ module Planter
       [u, rec.except(*unique_columns)]
     end
 
-    def association_options
-      @association_options ||=
-        model.constantize.reflect_on_association(parent).options
-    end
-
-    def primary_key
-      @primary_key ||=
-        association_options.fetch(:primary_key, :id)
-    end
-
     def foreign_key
-      @foreign_key ||=
-        association_options.fetch(:foreign_key, "#{parent}_id")
-    end
-
-    def parent_model
-      @parent_model ||=
-        association_options.fetch(:class_name, parent.to_s.classify)
-    end
-
-    def full_csv_name
-      @full_csv_name ||=
-        %W[#{csv_name}.csv #{csv_name}.csv.erb #{csv_name}.erb.csv]
-          .map { |f| Rails.root.join(Planter.config.csv_files_directory, f).to_s }
-          .find { |f| ::File.file?(f) }
+      adapter.foreign_key(model_name: model, parent: parent)
     end
 
-    def extract_data_from_csv
-      contents = ::File.read(full_csv_name)
-      if full_csv_name.include?(".erb")
-        contents = ERB.new(contents, trim_mode: erb_trim_mode).result(binding)
-      end
-
-      @data ||= ::CSV.parse(
-        contents,
-        headers: true,
-        header_converters: :symbol
-      ).map(&:to_hash)
+    def adapter
+      Planter.config.adapter
     end
   end
 end

data/lib/planter/version.rb

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

data/lib/planter.rb

@@ -69,7 +69,10 @@ module Planter
   #   Planter.seed
   def seed
     seeders = ENV["SEEDERS"]&.split(",") || config.seeders&.map(&:to_s)
-    raise "No seeders specified" if seeders.blank?
+    if seeders.blank?
+      warn "WARNING: Planter.seed was called, but no seeders were specified. Add seeders to config.seeders in config/initializers/planter.rb or set SEEDERS."
+      return
+    end
 
     seeders.each do |s|
       require Rails.root.join(config.seeders_directory, "#{s}_seeder.rb").to_s

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: planter
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Evan Gray
@@ -57,6 +57,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.22.0
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
@@ -82,9 +96,11 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- lib/generators/planter/adapter_generator.rb
 - lib/generators/planter/initializer_generator.rb
 - lib/generators/planter/seeder_generator.rb
 - lib/planter.rb
+- lib/planter/adapters/active_record.rb
 - lib/planter/config.rb
 - lib/planter/railtie.rb
 - lib/planter/seeder.rb