planter 0.4.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65e5880dfef8ccce0bf8fec627a74ab7ee76c9d0f84379079056d934b9210e58
-  data.tar.gz: 2bc7f2d1e88618db03c882291e8dc48b3aa453199f96e235eeab49ec554d0273
+  metadata.gz: b66f9b16f720b193d4dee6e0a23382b22a073982634bccbad2d52092516090eb
+  data.tar.gz: 5d66d7905379b7b148586b52b85afb2d715501543e88f0d84a88973b734d9f6b
 SHA512:
-  metadata.gz: 011cec287611791d0585a80c83e51bd602eafb9bba60755c5079b1eff6f5218ca3a05e21f1651098acda55055590ae4d9ca649f50e3f4559ca7cd971acf647c4
-  data.tar.gz: 5a11daf5df589cda533596d9039820c0da140f2c2f44eafb40d33a110cbd3aa7fef0a18c78c8c2f7f8d7a4a6dd8ab1f2e3a4d1a0a7a9f3dee3665fece5ff4fd6
+  metadata.gz: dde579bb6c055ce0c819148d1d818b39bf44ef9e75c692799dd760c7f9a96a0828d959f3204e6741fa55c41a6b9c2d8045f746142c139b5f20f1ea450ba7b259
+  data.tar.gz: 9f208c04796ae9f80ce6d46b4ec94e56da4fc2c62c36abf3198d806621bf2c7d79d9f52fd2d30ad0ee73c94206e7f0997b953ff93dbc93b83ff8064ee7ab85ed

data/README.md

@@ -1,7 +1,7 @@
 # Planter
 [![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fevanthegrayt%2Fplanter%2Fbadge%3Fref%3Dmaster&style=flat)](https://actions-badge.atrox.dev/evanthegrayt/planter/goto?ref=master)
-[![Gem Version](https://badge.fury.io/rb/planter.svg)](https://badge.fury.io/rb/planter)
-![Language: Ruby](https://img.shields.io/static/v1?label=language&message=Ruby&color=CC342D&style=flat&logo=ruby&logoColor=CC342D)
+[![Language: Ruby](https://img.shields.io/static/v1?label=language&message=Ruby&color=CC342D&style=flat&logo=ruby&logoColor=CC342D)](https://www.ruby-lang.org/)
+[![Gem Version](https://img.shields.io/gem/v/planter.svg)](https://rubygems.org/gems/planter)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 Seeds for Rails applications can get complicated fast, and Rails doesn't provide
@@ -18,12 +18,10 @@ Features include:
 You can view the documentation [here](https://evanthegrayt.github.io/planter/).
 
 ## Installation
-Add the following line to your application's Gemfile. Because this plugin is
-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.
+Add the following line to your application's Gemfile.
 
 ```ruby
-gem 'planter', '0.4.2'
+gem 'planter'
 ```
 
 And then execute:
@@ -97,10 +95,29 @@ into the existing `db:seed` task, simply add the following to `db/seeds.rb`.
 Planter.seed
 ```
 
+Before seeding, you can validate your Planter configuration without creating
+records.
+
+```bash
+rails planter:validate
+```
+
+This command loads the Rails environment, checks the configured seeders, and
+verifies that the configured adapter exposes Planter's adapter API. It prints a
+success message when no issues are found, warnings for non-fatal issues, and
+errors before exiting non-zero when the seed plan is not valid.
+
+Like `planter:seed`, validation supports the `SEEDERS` environment variable if
+you want to check only part of the configured plan.
+
+```bash
+rails planter:validate SEEDERS=users,addresses
+```
+
 To create a users seeder, run `rails generate planter:seeder users`. Usually,
 seeders seed a specific table, so it's recommended to name your seeders after
-the table. If you don't, you'll need to manually specify a few things. More on
-that later. This will create a file named `db/seeds/users_seeder.rb` (the
+the table. If you don't, specify the table with the `table` option in
+`seeding_method`. This will create a file named `db/seeds/users_seeder.rb` (the
 directory will be created if it doesn't exist) with the following contents.
 
 ```ruby
@@ -108,7 +125,7 @@ class UsersSeeder < Planter::Seeder
   # TODO: Choose a seeding_method. For example:
   # seeding_method :csv
 
-  # For now, we overload the seed method so no exception will be raised.
+  # For now, we override the seed method so no exception will be raised.
   def seed
   end
 end
@@ -122,15 +139,38 @@ correct order, you'll need to adjust the array manually.
 - When adjusting the array, always keep the closing bracket on its own line, or
 the generator won't know where to put the new seeders.
 
+You can also tell the generator which seeding style to use.
+
+```bash
+rails generate planter:seeder users --seeding-method=csv
+rails generate planter:seeder users --seeding-method=data-array
+rails generate planter:seeder users --seeding-method=custom
+```
+
+`--seeding-method=csv` creates a seeder with `seeding_method :csv` and creates
+`db/seed_files/users.csv` with headers pulled from the `users` table.
+`--seeding-method=data-array` creates a seeder with `seeding_method :data_array`
+and an empty `data` method. `--seeding-method=custom` creates a seeder with an
+empty `seed` method, which is useful when the built-in seeding methods don't
+fit.
+
 If you want to generate a seeder for every table currently in your database, run
-`rails generate planter:seeder ALL`.
+`rails generate planter:seeder ALL`. The seeding style options can be used with
+`ALL`, too; for example,
+`rails generate planter:seeder ALL --seeding-method=csv`.
 
 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.
+Each generated seeder needs a seeding method. In practice:
+
+- Use `csv` when the seed data should live in a file that is easy to review or
+  edit outside Ruby.
+- Use `data_array` when the seed data should be generated dynamically in Ruby.
+- Use a custom `seed` method when the built-in persistence flow is not the right
+  fit for the job.
 
 ### Seeding from CSV
 To seed from CSV, you simply need to add the following to your seeder class.
@@ -141,9 +181,27 @@ class UsersSeeder < Planter::Seeder
 end
 ```
 
-Then, create a directory called `db/seed_files`, and create a csv file called
-`db/seed_files/users.csv`. In this file, the header should be the field names,
-and the rest of the rows should be the corresponding data.
+Then, create a directory called `db/seed_files`, and create a CSV file called
+`db/seed_files/users.csv`. You can also run
+`rails generate planter:seeder users --seeding-method=csv` to create this file
+automatically. In this file, the headers should be the field names, and the rest
+of the rows should be the corresponding data.
+
+```
+email,username
+test1@example.com,test1
+test2@example.com,test2
+```
+
+For idempotent seeds, pass `unique_columns` to control which columns are used to
+find existing records. This example finds users by email and only uses
+`username` when creating a new record.
+
+```ruby
+class UsersSeeder < Planter::Seeder
+  seeding_method :csv, unique_columns: :email
+end
+```
 
 ```
 email,username
@@ -151,13 +209,35 @@ test1@example.com,test1
 test2@example.com,test2
 ```
 
+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.
+
+```ruby
+class RolesUsersSeeder < Planter::Seeder
+  seeding_method :csv
+end
+```
+
+```
+user_id,role_id
+1,1
+2,1
+```
+
 If the CSV file is named differently than the seeder, you can specify the
 `:csv_name` option. Note that the value should not include the file extension.
+If the seeder name does not match the table being seeded, specify the `:table`
+option.
 
 ```ruby
 class UsersSeeder < Planter::Seeder
   seeding_method :csv, csv_name: :people
 end
+
+class PeopleSeeder < Planter::Seeder
+  seeding_method :csv, table: :users
+end
 ```
 
 `ERB` can be used in the CSV files if you end the file name with `.csv.erb` or
@@ -203,7 +283,7 @@ end
 For help with `erb_trim_mode`, see the help documentation for `ERB::new`.
 
 Lastly, it's worth mentioning `transformations` under the CSV section, as that's
-usually the pace where they're needed most, but it will work with any method.
+usually the place where they're needed most, but they work with any method.
 
 If you're seeding with a CSV, and it contains values that need to have code
 executed on them before it's imported into the database, you can define an
@@ -264,12 +344,13 @@ the `Planter::Seeder` parent class automatically provides `attr_reader :data`.
 
 Running `rails planter:seed` should now seed your `users` table.
 
-You can also seed children records for every existing record of a parent model.
+You can also seed child records for every existing record of a parent relation.
 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 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.
+is interpreted by the configured adapter. With the default Active Record adapter,
+it should be the name of the `belongs_to` association on a model-backed table.
+The primary key, foreign key, and persistence details will all be determined by
+the adapter.
 
 ```ruby
 require 'faker'
@@ -289,11 +370,13 @@ end
 ```
 
 Note that specifying `number_of_records` in this instance will create that many
-records *for each record of the parent model*.
+records *for each record of the parent relation*.
 
 ### Custom seeds
-To write your own custom seeds, just overload the `seed` method and do whatever
-you need to do.
+To write your own custom seeds, generate with `--seeding-method=custom` or
+override the `seed` method and do whatever you need to do. This is the right
+choice when the seed depends on application-specific service objects, multiple
+tables, or logic that does not map cleanly to CSV or `data_array`.
 
 ```ruby
 class UsersSeeder < Planter::Seeder
@@ -312,7 +395,13 @@ end
 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.
+your ordered seed plan. The default adapter creates records through Active
+Record models when they exist, and falls back to direct table inserts for
+model-less tables such as join tables.
+
+For a full tutorial, see the
+[Writing a Custom Adapter](https://github.com/evanthegrayt/planter/wiki/Writing-a-Custom-Adapter)
+wiki page.
 
 You can generate a custom adapter stub with the following command.
 
@@ -320,11 +409,8 @@ You can generate a custom adapter stub with the following command.
 $ 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`.
+This creates `lib/planter/adapters/sequel.rb` with the required adapter methods,
+updates `config/initializers/planter.rb`, and leaves `config.seeders` unchanged.
 
 ```ruby
 require 'planter'
@@ -335,25 +421,26 @@ Planter.configure do |config|
 end
 ```
 
-Custom adapters are duck typed. They should implement the same public API as
+Custom adapters are duck typed. They do not need to expose model objects; at
+minimum, they should implement the same table-oriented 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.
+  def create_record(context:, lookup_attributes:, create_attributes:)
+    # Find or create a record for context.table_name.
   end
 
-  def parent_ids(model_name:, parent:)
+  def parent_ids(context:)
     # Return ids for each parent record used by parent seeding.
   end
 
-  def foreign_key(model_name:, parent:)
+  def foreign_key(context:)
     # Return the attribute used to attach a parent id to the seeded record.
   end
 
-  def table_columns(model_name:)
-    # Return native columns or fields for model_name.
+  def table_columns(context:)
+    # Return native columns or fields for context.table_name.
   end
 
   def table_names
@@ -372,8 +459,10 @@ issue](https://github.com/evanthegrayt/planter/issues/new). Just make sure
 the topic doesn't already exist. Better yet, you can always submit a Pull
 Request.
 
-## Self-Promotion
-I do these projects for fun, and I enjoy knowing that they're helpful to people.
-Consider starring [the repository](https://github.com/evanthegrayt/planter)
-if you like it! If you love it, follow me [on
-GitHub](https://github.com/evanthegrayt)!
+## Support this project
+I love knowing when people find my work useful. Any kind of support is very much
+appreciated!
+
+- ⭐️ Like the project? Star [the repository](https://github.com/evanthegrayt/planter)!
+- ❤️ Love the project? Follow me [on GitHub](https://github.com/evanthegrayt)!
+- 💸 *Really* love it? Consider [buying me a tea](https://paypal.me/evanrgray)!

data/lib/generators/planter/adapter_generator.rb

@@ -1,10 +1,17 @@
 module Planter
+  ##
+  # Namespace for Rails generators provided by Planter.
   module Generators
+    ##
+    # Rails generator that creates a custom adapter stub and configures Planter
+    # to use it.
     class AdapterGenerator < Rails::Generators::Base
       argument :adapter, required: true
 
       desc "Creates an adapter file at lib/planter/adapters"
 
+      ##
+      # Create a custom adapter file with the required adapter API.
       def generate_adapter
         create_file adapter_path, <<~RUBY
           # frozen_string_literal: true
@@ -12,12 +19,12 @@ module Planter
           module Planter
             module Adapters
               ##
-              # Custom adapter for Planter.
+              # Custom table-oriented adapter for Planter.
               class #{adapter_class_name}
                 ##
                 # 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
                 #
@@ -25,41 +32,37 @@ module Planter
                 #   creating a new record
                 #
                 # @return [Object]
-                def create_record(model_name:, lookup_attributes:, create_attributes:)
+                def create_record(context:, 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
+                # @param [Planter::SeedContext] context seeder configuration
                 #
                 # @return [Array]
-                def parent_ids(model_name:, parent:)
+                def parent_ids(context:)
                   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
+                # @param [Planter::SeedContext] context seeder configuration
                 #
                 # @return [String, Symbol]
-                def foreign_key(model_name:, parent:)
+                def foreign_key(context:)
                   raise NotImplementedError, "\#{self.class} must implement #foreign_key"
                 end
 
                 ##
-                # Return native columns or fields for the model being seeded.
+                # Return native columns or fields for the table being seeded.
                 #
-                # @param [String] model_name the model being seeded
+                # @param [Planter::SeedContext] context seeder configuration
                 #
                 # @return [Array<String>]
-                def table_columns(model_name:)
+                def table_columns(context:)
                   raise NotImplementedError, "\#{self.class} must implement #table_columns"
                 end
 
@@ -76,6 +79,8 @@ module Planter
         RUBY
       end
 
+      ##
+      # Update the Planter initializer to require and configure the new adapter.
       def update_initializer
         contents = ::File.read(initializer_full_path)
         contents = replace_or_insert_adapter_require(contents)

data/lib/generators/planter/initializer_generator.rb

@@ -1,8 +1,14 @@
 module Planter
+  ##
+  # Namespace for Rails generators provided by Planter.
   module Generators
+    ##
+    # Rails generator that creates Planter's initializer.
     class InitializerGenerator < Rails::Generators::Base
-      desc "Genrates an initializer for Planter at config/initializers/planter.rb"
+      desc "Generates an initializer for Planter at config/initializers/planter.rb"
 
+      ##
+      # Create the default Planter initializer file.
       def create_initializer_file
         create_file "config/initializers/planter.rb", <<~EOF
           require 'planter'

data/lib/generators/planter/seeder_generator.rb

@@ -1,10 +1,34 @@
 module Planter
+  ##
+  # Namespace for Rails generators provided by Planter.
   module Generators
+    ##
+    # Rails generator that creates one or more Planter seeder files.
+    #
+    # By default, generated seeders include a TODO comment and an empty +seed+
+    # method so they do not raise until a seeding method is chosen. Pass
+    # +--seeding-method=csv+, +--seeding-method=data-array+, or
+    # +--seeding-method=custom+ to generate a seeder for a specific style. The
+    # +csv+ method also creates a CSV seed file with headers pulled from the
+    # table being seeded.
     class SeederGenerator < Rails::Generators::Base
+      ##
+      # Generator-supported seeding method templates.
+      #
+      # @return [Array<Symbol>]
+      SEEDING_METHODS = %i[csv data_array custom].freeze
+
       argument :seeder, required: true
 
+      class_option :seeding_method,
+        type: :string,
+        desc: "Generate a seeder for a specific method: csv, data-array, or custom"
+
       desc "Creates a seeder file at #{::Planter.config.seeders_directory}"
 
+      ##
+      # Generate the requested seeder, or generate a seeder for every table
+      # when the argument is +ALL+.
       def generate_seeders
         (seeder == "ALL") ? tables.each { |t| generate(t) } : generate(seeder)
       end
@@ -14,22 +38,98 @@ module Planter
       def generate(seeder)
         empty_directory ::Planter.config.seeders_directory
 
-        create_file "#{::Planter.config.seeders_directory}/#{seeder}_seeder.rb", <<~EOF
-          class #{seeder.camelize}Seeder < Planter::Seeder
-            # TODO: Choose a seeding_method. For example:
-            # seeding_method :csv
+        create_file(
+          "#{::Planter.config.seeders_directory}/#{seeder}_seeder.rb",
+          [
+            "class #{seeder.camelize}Seeder < Planter::Seeder",
+            indent(seeder_contents),
+            "end",
+            ""
+          ].join("\n")
+        )
 
-            # For now, we overload the seed method so no exception will be raised.
-            def seed
-            end
-          end
-        EOF
+        create_csv(seeder) if selected_seeding_method == :csv
 
         inject_into_file "config/initializers/planter.rb",
           "    #{seeder}\n",
           before: /^\s*\]\s*$/
       end
 
+      def seeder_contents
+        case selected_seeding_method
+        when :csv
+          "seeding_method :csv"
+        when :data_array
+          <<~RUBY.rstrip
+            seeding_method :data_array
+
+            def data
+              [
+              ]
+            end
+          RUBY
+        when :custom
+          custom_seed_contents
+        else
+          [
+            "# TODO: Choose a seeding_method. For example:",
+            "# seeding_method :csv",
+            "",
+            "# For now, we override the seed method so no exception will be raised.",
+            custom_seed_contents
+          ].join("\n")
+        end
+      end
+
+      def custom_seed_contents
+        <<~RUBY.rstrip
+          def seed
+          end
+        RUBY
+      end
+
+      def indent(contents)
+        contents.lines.map do |line|
+          line.strip.empty? ? line : "  #{line}"
+        end.join
+      end
+
+      def selected_seeding_method
+        return unless options["seeding_method"]
+
+        method = options["seeding_method"].tr("-", "_").to_sym
+        unless SEEDING_METHODS.include?(method)
+          raise Thor::Error, "Expected --seeding-method to be one of: csv, data-array, custom"
+        end
+
+        method
+      end
+
+      def create_csv(seeder)
+        empty_directory ::Planter.config.csv_files_directory
+
+        create_file(
+          "#{::Planter.config.csv_files_directory}/#{seeder}.csv",
+          "#{csv_headers(seeder).join(",")}\n"
+        )
+      end
+
+      def csv_headers(seeder)
+        ::Planter.config.adapter.table_columns(context: csv_context(seeder))
+      end
+
+      def csv_context(seeder)
+        ::Planter::SeedContext.new(
+          table_name: seeder,
+          seed_method: :csv,
+          csv_name: seeder,
+          parent: nil,
+          number_of_records: 1,
+          unique_columns: nil,
+          erb_trim_mode: ::Planter.config.erb_trim_mode
+        )
+      end
+
       def tables
         @tables ||= ::Planter.config.adapter.table_names
       end