multi_insert 0.2.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fc4fbdea86f270f216a65ede4de9f283ad443ea0
-  data.tar.gz: f1a8f163a22a3b1c1dd261f2e47c3bde55fb549b
+  metadata.gz: '09249bbd92253e001ba2eda9b5229ba076f5fa47'
+  data.tar.gz: fa5a964166797cce48283e4dfd2dd1baf2426fd3
 SHA512:
-  metadata.gz: 25ab114fd113733f6d6eebc55b6a9823dcdbe50a67d8613de9ff8116386acc915dff79197aff2e4925a6dfc1b3b1856e963f03c70f20e2ea46d1b9ec69fb9561
-  data.tar.gz: ee85021afd8623963c931a16757b577e5f875cf1d711cba08de4fe57a3a30dfac8d3837a94a5849d6683961bd5cfb9d21eddfafbad7e5b9da1a64213106b601c
+  metadata.gz: 507b36948e987722d93c623bfa5a743fddd970d03926439f81b5c577f75da3dc5c5aeb2a1d23162e362fe2c8df1f27670a003efd8b6d2e88914f2c85b076e3c2
+  data.tar.gz: 2bd855e0af71b62829b7be80d7d3e452fcce4c7de3079299b6b56d8b1ff4d67f48649cb9d5180d136f87b6f282bee8805d3b18784fdece2309150effd9fd4bf2

data/lib/multi_insert/hooks/active_record.rb

@@ -2,6 +2,14 @@ require 'active_record'
 require 'multi_insert/query'
 
 class ActiveRecord::Base
+  # Start a multi insert.
+  #
+  # See `Query#new` for a list of options.
+  #
+  # @param columns [Array<Symbol | String>] The columns to use for insertion.
+  # @param values [Array<Array<String | Number | Boolean | nil>>] Values to be inserted.
+  # @param opts [Hash<Object>] Options.
+  # @return [Query] A query object.
   def self.multi_insert(columns, values, opts = {})
     ::MultiInsert::Query.new(self.table_name, columns, values, opts)
   end

data/lib/multi_insert/query.rb

@@ -1,18 +1,43 @@
 require 'active_record'
 require 'multi_insert/query_builder'
 
+# Top level module for MultiInsert.
 module MultiInsert
+  # A MultiInsert query.
+  #
+  # Most of the time, you do not need to instanciate it yourself.
   class Query
+    # A conflict close inside a query.
+    #
+    # You never need to instanciate it yourself. Instead, use `Query#on_conflict`.
     class OnConflict
+      # Create an ON CONFLICT clause
+      #
+      # @param query [Query] the query.
+      # @param column [String | Symbol] the column to watch for conflicts.
       def initialize(query, column)
         @query = query
         @column = column.to_sym
       end
 
+      # Ignore conflicting rows.
+      #
+      # @return [Query] the original query.
       def do_nothing
         @query.on_conflict_sql(::MultiInsert::QueryBuilder.on_conflict_do_nothing(@column))
       end
 
+      # Update the conflicting rows according to user-supplied rules.
+      #
+      # The rules can be:
+      # - A single symbol or string denoting a column name. In this case, the matching column will be updated.
+      # - An array of strings or symbols. In this case, the matching columns will be updated.
+      # - An hash of values (Integers or Strings) or the symbol `:excluded`. The matching columns will be updated
+      # to the supplied values, except when the value is `:excluded`. In that case, the matching columns will be set
+      # to the value to be inserted.
+      #
+      # @param values [String | Symbol | Array<String | Symbol> | Hash<String | Symbol => String | Number | Boolean>] The user specified rules.
+      # @return [Query] The original query.
       def do_update(values)
         @query.on_conflict_sql(::MultiInsert::QueryBuilder.on_conflict_do_update(@column, values, @query.opts))
       end
@@ -20,41 +45,80 @@ module MultiInsert
 
     attr_reader :opts
 
+    # Create an insert query against the specified table and columns, with the specified values.
+    # The following options are supported:
+    # - time (true) Whether to insert created_at and updated_at.
+    #
+    # @param table [String | Symbol] The table to be used for insertion.
+    # @param columns [Array<String | Symbol>] The columns to be inserted.
+    # @param values [Array<Array<String | Number | Boolean>>] The values to be inserted.
+    # @param opts [Hash<Object>] Options.
     def initialize(table, columns, values, opts = {})
       @table = table.to_sym
       @opts = opts
       @sql_insert = ::MultiInsert::QueryBuilder.insert(table, columns, values, opts)
     end
 
+    # Add a returning clause to the query.
+    #
+    # @param columns [Array<Symbol | String>] The columns to return.
+    # @return [Query] self.
     def returning(columns)
       @sql_returning = ::MultiInsert::QueryBuilder.returning(columns)
       @returning_flat = false
       self
     end
 
+    # Add a returning clause to the query, returning IDs.
+    #
+    # The IDs will be returned as a flat array.
+    # @return [Query] self
     def returning_id
       @sql_returning = ::MultiInsert::QueryBuilder.returning([:id])
       @returning_flat = true
       self
     end
 
+    # Begin a conflict clause.
+    #
+    # @param column [String | Symbol] The column to watch for conflicts.
+    # @return [Query::OnConflict] A conflict clause.
     def on_conflict(column)
       ::MultiInsert::Query::OnConflict.new(self, column)
     end
 
+    # Handle a conflict with raw SQL
+    #
+    # You should probably use the friendly helper method instead.
+    # @param sql [String] An SQL expression starting with "ON CONFLICT".
+    # @return [Query] self.
     def on_conflict_sql(sql)
       @sql_on_conflict = sql
       self
     end
 
+    # Convert the query to raw SQL.
+    #
+    # @return [String] An SQL query.
     def to_sql
       [@sql_insert, @sql_on_conflict, @sql_returning].reject(&:nil?).join(' ')
     end
 
+    # Equivalent to `to_sql`.
+    #
+    # @return [String] An SQL query.
     def to_s
       to_sql
     end
 
+    # Execute the query, and return eventual results.
+    #
+    # Result may be:
+    # - Nil if no returning clause was present.
+    # - An array of IDs if the returning_id helper was called.
+    # - An array of rows otherwise.
+    #
+    # @return [nil | Array<Integer> | Array<Array<String | Number | Boolean>>]
     def execute
       result = ActiveRecord::Base.connection.execute(to_sql)
       if @sql_returning.nil?

data/lib/multi_insert/query_builder.rb

@@ -53,7 +53,8 @@ module MultiInsert
         now = Time.now.to_s(:db)
         values[:updated_at] = now
       end
-      values.map! do |key, value|
+      arr = []
+      values.each do |key, value|
         v = nil
         key = ActiveRecord::Base.connection.quote_column_name(key.to_s)
         if value == :excluded
@@ -61,9 +62,9 @@ module MultiInsert
         else
           v = ActiveRecord::Base.connection.quote(value)
         end
-        "#{key} = #{v}"
+        arr << "#{key} = #{v}"
       end
-      values = values.join(', ')
+      values = arr.join(', ')
       "#{on_conflict(column)} DO UPDATE SET #{values}"
     end
 

data/lib/multi_insert/version.rb

@@ -1,3 +1,4 @@
 module MultiInsert
-  VERSION = "0.2.1"
+  # The version number for MultiInsert.
+  VERSION = "1.0.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: multi_insert
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Nax