planter 0.4.1 → 0.5.0

data/lib/planter/adapters/active_record.rb

@@ -1,24 +1,31 @@
 # frozen_string_literal: true
 
 module Planter
+  ##
+  # Namespace for persistence adapters used by Planter seeders.
   module Adapters
     ##
-    # Default adapter for seeding Active Record models.
+    # Default adapter for seeding Active Record tables.
+    #
+    # When a table maps to an Active Record model, records are created through
+    # that model. Tables without a matching model, such as join tables, are
+    # seeded directly through the database connection.
     #
     # 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:)+
+    # - +create_record(context:, lookup_attributes:, create_attributes:)+
+    # - +parent_ids(context:)+
+    # - +foreign_key(context:)+
+    # - +table_columns(context:)+
     # - +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.
+    # +context+ is a +Planter::SeedContext+. 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 [Planter::SeedContext] context seeder configuration
       #
       # @param [Hash] lookup_attributes attributes used to find the record
       #
@@ -26,34 +33,52 @@ module Planter
       #   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)
+      def create_record(context:, lookup_attributes:, create_attributes:)
+        if (model = model(context))
+          model
+            .where(lookup_attributes)
+            .first_or_create!(create_attributes)
+        else
+          create_table_record(context, lookup_attributes, create_attributes)
+        end
       end
 
       ##
       # Return the parent ids to use when seeding child records.
       #
-      # @param [String] model_name the model being seeded
+      # The Active Record adapter resolves parents through model associations.
+      # Tables without matching models should use a custom adapter for parent
+      # seeding.
       #
-      # @param [String, Symbol] parent the parent association name
+      # @param [Planter::SeedContext] context seeder configuration
       #
       # @return [Array]
-      def parent_ids(model_name:, parent:)
-        parent_model(model_name, parent).constantize.pluck(primary_key(model_name, parent))
+      def parent_ids(context:)
+        parent_model(context).constantize.pluck(primary_key(context))
       end
 
       ##
       # Return the foreign key used to assign a parent id on a child record.
       #
-      # @param [String] model_name the model being seeded
+      # The Active Record adapter resolves foreign keys through model
+      # associations. Tables without matching models should use a custom adapter
+      # for parent seeding.
       #
-      # @param [String, Symbol] parent the parent association name
+      # @param [Planter::SeedContext] context seeder configuration
       #
       # @return [String, Symbol]
-      def foreign_key(model_name:, parent:)
-        association_options(model_name, parent).fetch(:foreign_key, "#{parent}_id")
+      def foreign_key(context:)
+        association_options(context).fetch(:foreign_key, "#{context.parent}_id")
+      end
+
+      ##
+      # Return native table columns for the table being seeded.
+      #
+      # @param [Planter::SeedContext] context seeder configuration
+      #
+      # @return [Array<String>]
+      def table_columns(context:)
+        ::ActiveRecord::Base.connection.columns(context.table_name).map(&:name)
       end
 
       ##
@@ -68,16 +93,77 @@ module Planter
 
       private
 
-      def association_options(model_name, parent)
-        model_name.constantize.reflect_on_association(parent).options
+      def model(context)
+        context.table_name.classify.safe_constantize&.then do |model|
+          model if model.respond_to?(:table_name) && model.table_name == context.table_name
+        end
+      end
+
+      def association_options(context)
+        model!(context).reflect_on_association(context.parent).options
+      end
+
+      def primary_key(context)
+        association_options(context).fetch(:primary_key, :id)
+      end
+
+      def parent_model(context)
+        association_options(context).fetch(:class_name, context.parent.to_s.classify)
+      end
+
+      def model!(context)
+        model(context) || raise(
+          "Planter's Active Record adapter requires a model-backed table for " \
+          "parent seeding. Define a model for #{context.table_name} or use a " \
+          "custom adapter."
+        )
+      end
+
+      def create_table_record(context, lookup_attributes, create_attributes)
+        find_table_record(context, lookup_attributes) ||
+          insert_table_record(context, lookup_attributes.merge(create_attributes))
+      end
+
+      def find_table_record(context, lookup_attributes)
+        connection.select_one(
+          [
+            "SELECT * FROM #{quote_table(context.table_name)}",
+            "WHERE #{where_clause(lookup_attributes)}",
+            "LIMIT 1"
+          ].join(" ")
+        )
+      end
+
+      def insert_table_record(context, attributes)
+        connection.execute(
+          [
+            "INSERT INTO #{quote_table(context.table_name)}",
+            "(#{attributes.keys.map { |key| quote_column(key) }.join(", ")})",
+            "VALUES (#{attributes.values.map { |value| connection.quote(value) }.join(", ")})"
+          ].join(" ")
+        )
+      end
+
+      def where_clause(attributes)
+        attributes.map do |key, value|
+          if value.nil?
+            "#{quote_column(key)} IS NULL"
+          else
+            "#{quote_column(key)} = #{connection.quote(value)}"
+          end
+        end.join(" AND ")
+      end
+
+      def quote_table(table_name)
+        connection.quote_table_name(table_name)
       end
 
-      def primary_key(model_name, parent)
-        association_options(model_name, parent).fetch(:primary_key, :id)
+      def quote_column(column_name)
+        connection.quote_column_name(column_name)
       end
 
-      def parent_model(model_name, parent)
-        association_options(model_name, parent).fetch(:class_name, parent.to_s.classify)
+      def connection
+        ::ActiveRecord::Base.connection
       end
     end
   end

data/lib/planter/config.rb

@@ -53,8 +53,8 @@ module Planter
 
     ##
     # 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+.
+    # database table names. Custom adapters should implement the table-oriented
+    # public API documented by +Planter::Adapters::ActiveRecord+.
     #
     # @return [Object]
     attr_writer :adapter

data/lib/planter/csv_data_source.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Planter
+  ##
+  # Loads CSV seed data for a configured seeder.
+  class CsvDataSource
+    ##
+    # Create a CSV data source.
+    #
+    # @param [Planter::SeedContext] context seeder configuration
+    #
+    # @param [Planter::Seeder] seeder seeder instance used for ERB binding
+    def initialize(context:, seeder:)
+      @context = context
+      @seeder = seeder
+    end
+
+    ##
+    # Return parsed CSV rows as hashes.
+    #
+    # @return [Array<Hash>]
+    def data
+      contents = ::File.read(path)
+      if path.include?(".erb")
+        contents = ERB.new(contents, trim_mode: context.erb_trim_mode).result(seeder_binding)
+      end
+
+      ::CSV.parse(
+        contents,
+        headers: true,
+        header_converters: :symbol
+      ).map(&:to_hash)
+    end
+
+    ##
+    # Return the first matching CSV path for the configured CSV name.
+    #
+    # @return [String, nil]
+    def path
+      @path ||=
+        %W[#{context.csv_name}.csv #{context.csv_name}.csv.erb #{context.csv_name}.erb.csv]
+          .map { |file| Rails.root.join(Planter.config.csv_files_directory, file).to_s }
+          .find { |file| ::File.file?(file) }
+    end
+
+    private
+
+    attr_reader :context, :seeder
+
+    def seeder_binding
+      seeder.instance_eval { binding }
+    end
+  end
+end

data/lib/planter/record_attributes.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Planter
+  ##
+  # Prepares seed records for adapter persistence.
+  class RecordAttributes
+    ##
+    # Create a record attribute preparer.
+    #
+    # @param [Planter::SeedContext] context seeder configuration
+    #
+    # @param [Object] adapter configured persistence adapter
+    #
+    # @param [#call] transformations_provider returns value transformations by
+    #   field
+    def initialize(context:, adapter:, transformations_provider:)
+      @context = context
+      @adapter = adapter
+      @transformations_provider = transformations_provider
+      @warned_non_column_lookup_attributes = []
+    end
+
+    ##
+    # Prepare lookup and create attributes for adapter persistence.
+    #
+    # @param [Hash] record seed record attributes
+    #
+    # @param [Object, nil] parent_id parent record id
+    #
+    # @return [Array<Hash, Hash>]
+    def prepare(record, parent_id: nil)
+      lookup_attributes, create_attributes = split_record(apply_transformations(record))
+      lookup_attributes = lookup_attributes.merge(foreign_key => parent_id) if parent_id
+
+      filter_lookup_attributes(lookup_attributes, create_attributes)
+    end
+
+    private
+
+    attr_reader :context, :adapter, :transformations_provider
+
+    def apply_transformations(record)
+      transformations = transformations_provider.call
+      return record if transformations.nil?
+
+      record.map { |field, value| map_record(field, value, record, transformations) }.to_h
+    end
+
+    def map_record(field, value, record, transformations)
+      [
+        field,
+        transformations.key?(field) ? transform(field, value, record, transformations) : value
+      ]
+    end
+
+    def transform(field, value, record, transformations)
+      case transformations[field].arity
+      when 0 then transformations[field].call
+      when 1 then transformations[field].call(value)
+      when 2 then transformations[field].call(value, record)
+      end
+    end
+
+    def split_record(record)
+      return [record, {}] unless context.unique_columns
+
+      lookup_attributes = context.unique_columns.each_with_object({}) do |column, attrs|
+        attrs[column] = record[column]
+      end
+      [lookup_attributes, record.except(*context.unique_columns)]
+    end
+
+    def filter_lookup_attributes(lookup_attributes, create_attributes)
+      native_lookup_attributes = lookup_attributes.select do |field, _value|
+        table_columns.include?(field.to_s)
+      end
+      non_column_lookup_attributes = lookup_attributes.except(*native_lookup_attributes.keys)
+
+      warn_non_column_lookup_attributes(non_column_lookup_attributes.keys) if non_column_lookup_attributes.any?
+
+      if native_lookup_attributes.empty?
+        raise "No native lookup columns found for #{context.table_name}. " \
+          "Add a native table column to the seed data or unique_columns."
+      end
+
+      [
+        native_lookup_attributes,
+        non_column_lookup_attributes.merge(create_attributes)
+      ]
+    end
+
+    def warn_non_column_lookup_attributes(fields)
+      warning_key = fields.map(&:to_s).sort
+      return if warned_non_column_lookup_attributes.include?(warning_key)
+
+      warned_non_column_lookup_attributes << warning_key
+      warn(
+        "WARNING: Planter moved non-column lookup attributes for #{context.table_name} " \
+        "into create attributes: #{warning_key.join(", ")}"
+      )
+    end
+
+    def foreign_key
+      @foreign_key ||= adapter.foreign_key(context: context)
+    end
+
+    def table_columns
+      @table_columns ||= adapter.table_columns(context: context).map(&:to_s)
+    end
+
+    attr_reader :warned_non_column_lookup_attributes
+  end
+end

data/lib/planter/seed_context.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Planter
+  ##
+  # Parameter object carrying normalized seeder configuration into adapters.
+  class SeedContext
+    ##
+    # The table being seeded.
+    #
+    # @return [String]
+    attr_reader :table_name
+
+    ##
+    # The configured seeding method.
+    #
+    # @return [Symbol, nil]
+    attr_reader :seed_method
+
+    ##
+    # The CSV seed file name without an extension.
+    #
+    # @return [String]
+    attr_reader :csv_name
+
+    ##
+    # The adapter-defined parent relation.
+    #
+    # @return [String, Symbol, nil]
+    attr_reader :parent
+
+    ##
+    # How many times to create each data record.
+    #
+    # @return [Integer]
+    attr_reader :number_of_records
+
+    ##
+    # Columns used to look up existing records.
+    #
+    # @return [Array<Symbol>, nil]
+    attr_reader :unique_columns
+
+    ##
+    # The ERB trim mode used for CSV templates.
+    #
+    # @return [String, nil]
+    attr_reader :erb_trim_mode
+
+    ##
+    # Create a new seed context.
+    #
+    # @param [String, Symbol] table_name
+    #
+    # @param [String, Symbol, nil] seed_method
+    #
+    # @param [String, Symbol] csv_name
+    #
+    # @param [String, Symbol, nil] parent
+    #
+    # @param [Integer] number_of_records
+    #
+    # @param [Array<Symbol>, nil] unique_columns
+    #
+    # @param [String, nil] erb_trim_mode
+    def initialize(
+      table_name:,
+      seed_method:,
+      csv_name:,
+      parent:,
+      number_of_records:,
+      unique_columns:,
+      erb_trim_mode:
+    )
+      @table_name = table_name.to_s
+      @seed_method = seed_method&.intern
+      @csv_name = csv_name.to_s
+      @parent = parent
+      @number_of_records = number_of_records
+      @unique_columns = unique_columns
+      @erb_trim_mode = erb_trim_mode
+    end
+  end
+end