db_fuel 1.0.0 → 1.1.0.pre.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 181a57c237b43052c5aa968663e4d3d6d8e6141a3affaf5b0de1ad4147e0725c
-  data.tar.gz: 817df3889c7c39f228cc2a860e19cd1cefb97f9ba23697972e04aa163413b359
+  metadata.gz: fb563756df642d23e7d268cf0e7b35735300ddfc84da31e0ee11d7e138d41584
+  data.tar.gz: f5720ed0f4649ba82d0c233cf9ccbc4aff5d54d8d9c4267c830467f43f85cdf3
 SHA512:
-  metadata.gz: d8bdbd205ee2c03f2954057f199c58e7d94d2ee64ebcc3735bb4a380dea175be7eb0ed9ac05e1dff12f985f8831e2bb15d76227d61bea0c4e3091b4185cb47d8
-  data.tar.gz: f03df133b8563d7e035654ccaab7c4789a818683dd68a4bf5471d4d7261ea53fcddf989ab5c5e91cbfd3bbc57cb1ed75ab86ec355496571aeb5b816ff4a19f35
+  metadata.gz: 16c63b0939d36f32cfc72baeefc20fbb88e7285d5c5e8266d337f55362909a6f751f7f2b1c535f6c231a11adba2693807c68e6af1b4d5eaaf4b14a9213589d01
+  data.tar.gz: a5143b01108dc065d98a5e085da06c8e82a5f0c084a0097128219e8c49542818a8ce754ef1af79be23d6493f259f745657bba4e74051cf856264fbe87a76dfde

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# 1.1.0 (TBD)
+
+New Jobs:
+
+* db_fuel/active_record/insert
+* db_fuel/active_record/update
+
 # 1.0.0 (November 18th, 2020)
 
 Initial implementation.  Includes jobs:

data/README.md

@@ -22,11 +22,39 @@ bundle add db_fuel
 
 Refer to the [Burner](https://github.com/bluemarblepayroll/burner) library for more specific information on how Burner works.  This section will just focus on what this library directly adds.
 
+### ActiveRecord Jobs
+
+* **db_fuel/active_record/insert** [table_name, attributes, debug, primary_key, register, separator, timestamps]: This job can take the objects in a register and insert them into a database table.  Attributes defines which object properties to convert to SQL.  Refer to the class and constructor specification for more detail.
+* **db_fuel/active_record/update** [table_name, attributes, debug, register, separator, timestamps, unique_keys]: This job can take the objects in a register and updates them within a database table.  Attributes defines which object properties to convert to SQL SET clauses while unique_keys translate to WHERE clauses.  Refer to the class and constructor specification for more detail.
+
+### Dbee Jobs
+
 * **db_fuel/dbee/query** [model, query, register]:  Pass in a [Dbee](https://github.com/bluemarblepayroll/dbee) model and query and store the results in the specified register.  Refer to the [Dbee](https://github.com/bluemarblepayroll/dbee) library directly on how to craft a model or query.
 * **db_fuel/dbee/range** [key, key_path, model, query, register, separator]: Similar to `db_fuel/dbee/query` with the addition of being able to grab a list of values from the register to use as a Dbee EQUALS/IN filter.  This helps to dynamically limit the resulting record set.  The key is used to specify where to grab the list of values, while the key_path will be used to craft the [Dbee equal's filter](https://github.com/bluemarblepayroll/dbee/blob/master/lib/dbee/query/filters/equals.rb).  Separator is exposed in case nested object support is necessary.
 
 ## Examples
 
+In all the examples we will assume we have the following schema:
+
+````ruby
+ActiveRecord::Schema.define do
+  create_table :statuses do |t|
+    t.string  :code,     null: false, limit: 25
+    t.integer :priority, null: false, default: 0
+    t.timestamps
+  end
+
+  create_table :patients do |t|
+    t.string     :chart_number
+    t.string     :first_name
+    t.string     :middle_name
+    t.string     :last_name
+    t.references :status
+    t.timestamps
+  end
+end
+````
+
 ### Querying the Database
 
 The `db_fuel/dbee/query` job can be utilized to process a SQL query and store the results in a Burner::Payload register.
@@ -53,8 +81,7 @@ pipeline = {
       },
       register: :patients
     }
-  ],
-  steps: %w[retrieve_patients]
+  ]
 }
 
 payload = Burner::Payload.new
@@ -105,8 +132,7 @@ pipeline = {
       key: :fname,
       key_path: :first_name
     }
-  ],
-  steps: %w[load_first_names retrieve_patients]
+  ]
 }
 
 payload = Burner::Payload.new
@@ -122,7 +148,95 @@ payload['patients'] # array in form of: [ { "id" => 1, "first_name" => "Somethin
 
 The only difference between the query and range jobs should be the latter is limited based on the incoming first names.
 
+### Updating the Database
+
+#### Inserting Records
+
+We can deal with persistence using the db_fuel/active_record/* jobs.  In order to insert new records we can use the `db_fuel/active_record/insert` job.  For example:
+
+````ruby
+pipeline = {
+  jobs: [
+    {
+      name: :load_patients,
+      type: 'b/value/static',
+      register: :patients,
+      value: [
+        { chart_number: 'B0001', first_name: 'Bugs', last_name: 'Bunny' },
+        { chart_number: 'B0002', first_name: 'Babs', last_name: 'Bunny' }
+      ]
+    },
+    {
+      name: 'insert_patients',
+      type: 'db_fuel/active_record/insert',
+      register: :patients,
+      attributes: [
+        { key: :chart_number },
+        { key: :first_name },
+        { key: :last_name }
+      ],
+      table_name: 'patients',
+      primary_key: {
+        key: :id
+      }
+    }
+  ]
+}
+
+payload = Burner::Payload.new
+
+Burner::Pipeline.make(pipeline).execute(payload: payload)
+````
+
+There should now be two new patients, AB0 and AB1, present in the table `patients`.
+
+Notes:
+
+* Since we specified the `primary_key`, the records' `id` attributes should be set to their respective primary key values.
+* Set `debug: true` to print out each INSERT statement in the output (not for production use.)
+
+#### Updating Records
+
+Let's say we now want to update those records' last names:
+
+````ruby
+pipeline = {
+  jobs: [
+    {
+      name: :load_patients,
+      type: 'b/value/static',
+      register: :patients,
+      value: [
+        { chart_number: 'B0001', last_name: 'Fox' },
+        { chart_number: 'B0002', last_name: 'Smurf' }
+      ]
+    },
+    {
+      name: 'update_patients',
+      type: 'db_fuel/active_record/update',
+      register: :patients,
+      attributes: [
+        { key: :last_name }
+      ],
+      table_name: 'patients',
+      unique_keys: [
+        { key: :chart_number }
+      ]
+    }
+  ]
+}
+
+payload = Burner::Payload.new
+
+Burner::Pipeline.make(pipeline).execute(payload: payload)
+````
+
+Each database record should have been updated with their new respective last names.
+
+Notes:
 
+* The unique_keys translate to WHERE clauses.
+* Set `debug: true` to print out each UPDATE statement in the output (not for production use.)
 ## Contributing
 
 ### Development Environment Configuration

data/db_fuel.gemspec

@@ -42,7 +42,7 @@ Gem::Specification.new do |s|
 
   s.add_dependency('activerecord', activerecord_version)
   s.add_dependency('acts_as_hashable', '~>1.2')
-  s.add_dependency('burner', '~>1.0')
+  s.add_dependency('burner', '~>1.2')
   s.add_dependency('dbee', '~>2.1')
   s.add_dependency('dbee-active_record', '~>2.1')
   s.add_dependency('objectable', '~>1.0')

data/lib/db_fuel.rb

@@ -14,4 +14,7 @@ require 'dbee'
 require 'dbee/providers/active_record_provider'
 require 'objectable'
 
+# General purpose classes used by the main job classes.
+require_relative 'db_fuel/modeling'
+
 require_relative 'db_fuel/library'

data/lib/db_fuel/library.rb

@@ -7,8 +7,19 @@
 # LICENSE file in the root directory of this source tree.
 #
 
+require_relative 'library/active_record/insert'
+require_relative 'library/active_record/update'
+
 require_relative 'library/dbee/query'
 require_relative 'library/dbee/range'
 
-Burner::Jobs.register('db_fuel/dbee/query', DbFuel::Library::Dbee::Query)
-Burner::Jobs.register('db_fuel/dbee/range', DbFuel::Library::Dbee::Range)
+module Burner
+  # Open up Burner::Jobs and add registrations for this libraries jobs.
+  class Jobs
+    register 'db_fuel/active_record/insert', DbFuel::Library::ActiveRecord::Insert
+    register 'db_fuel/active_record/update', DbFuel::Library::ActiveRecord::Update
+
+    register 'db_fuel/dbee/query', DbFuel::Library::Dbee::Query
+    register 'db_fuel/dbee/range', DbFuel::Library::Dbee::Range
+  end
+end

data/lib/db_fuel/library/active_record/base.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module DbFuel
+  module Library
+    module ActiveRecord
+      # This job can take the objects in a register and insert them into a database table.
+      #
+      # Expected Payload[register] input: array of objects
+      # Payload[register] output: array of objects.
+      class Base < Burner::JobWithRegister
+        CREATED_AT = :created_at
+        NOW_TYPE   = 'r/value/now'
+        UPDATED_AT = :updated_at
+
+        attr_reader :arel_table,
+                    :attribute_renderers,
+                    :debug,
+                    :resolver
+
+        def initialize(
+          name:,
+          table_name:,
+          attributes: [],
+          debug: false,
+          register: Burner::DEFAULT_REGISTER,
+          separator: ''
+        )
+          super(name: name, register: register)
+
+          @arel_table = ::Arel::Table.new(table_name.to_s)
+          @debug      = debug || false
+
+          # set resolver first since make_attribute_renderers needs it.
+          @resolver = Objectable.resolver(separator: separator)
+
+          @attribute_renderers = Burner::Modeling::Attribute
+                                 .array(attributes)
+                                 .map { |a| Burner::Modeling::AttributeRenderer.new(a, resolver) }
+        end
+
+        private
+
+        def timestamp_attribute(key)
+          Burner::Modeling::Attribute.make(
+            key: key,
+            transformers: [
+              { type: NOW_TYPE }
+            ]
+          )
+        end
+
+        def debug_detail(output, message)
+          return unless debug
+
+          output.detail(message)
+        end
+
+        def make_arel_row(row)
+          row.map { |key, value| [arel_table[key], value] }
+        end
+
+        def transform(row, time)
+          attribute_renderers.each_with_object({}) do |attribute_renderer, memo|
+            value = attribute_renderer.transform(row, time)
+
+            resolver.set(memo, attribute_renderer.key, value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/db_fuel/library/active_record/insert.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require_relative 'base'
+
+module DbFuel
+  module Library
+    module ActiveRecord
+      # This job can take the objects in a register and insert them into a database table.
+      #
+      # Expected Payload[register] input: array of objects
+      # Payload[register] output: array of objects.
+      class Insert < Base
+        attr_reader :primary_key
+
+        # Arguments:
+        #   name [required]: name of the job within the Burner::Pipeline.
+        #
+        #   table_name [required]: name of the table to use for the INSERT statements.
+        #
+        #   attributes:  Used to specify which object properties to put into the
+        #                SQL statement and also allows for one last custom transformation
+        #                pipeline, in case the data calls for sql-specific transformers
+        #                before insertion.
+        #
+        #   debug: If debug is set to true (defaults to false) then the SQL statements and
+        #          returned objects will be printed in the output.  Only use this option while
+        #          debugging issues as it will fill up the output with (potentially too much) data.
+        #
+        #   primary_key: If primary_key is present then it will be used to set the object's
+        #                property to the returned primary key from the INSERT statement.
+        #
+        #   separator: Just like other jobs with a 'separator' option, if the objects require
+        #              key-path notation or nested object support, you can set the separator
+        #              to something non-blank (like a period for notation in the
+        #              form of: name.first).
+        #
+        #   timestamps: If timestamps is true (default behavior) then both created_at
+        #               and updated_at columns will automatically have their values set
+        #               to the current UTC timestamp.
+        def initialize(
+          name:,
+          table_name:,
+          attributes: [],
+          debug: false,
+          primary_key: nil,
+          register: Burner::DEFAULT_REGISTER,
+          separator: '',
+          timestamps: true
+        )
+          explicit_attributes = Burner::Modeling::Attribute.array(attributes)
+
+          attributes = timestamps ? timestamp_attributes + explicit_attributes : explicit_attributes
+
+          super(
+            name: name,
+            table_name: table_name,
+            attributes: attributes,
+            debug: debug,
+            register: register,
+            separator: separator
+          )
+
+          @primary_key = Modeling::KeyedColumn.make(primary_key, nullable: true)
+
+          freeze
+        end
+
+        def perform(output, payload)
+          payload[register] = array(payload[register])
+
+          payload[register].each do |row|
+            arel_row       = make_arel_row(transform(row, payload.time))
+            insert_manager = ::Arel::InsertManager.new.insert(arel_row)
+
+            debug_detail(output, "Insert Statement: #{insert_manager.to_sql}")
+
+            id = ::ActiveRecord::Base.connection.insert(insert_manager)
+
+            resolver.set(row, primary_key.key, id) if primary_key
+
+            debug_detail(output, "Insert Return: #{row}")
+          end
+        end
+
+        private
+
+        def timestamp_attributes
+          [
+            timestamp_attribute(CREATED_AT),
+            timestamp_attribute(UPDATED_AT)
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/db_fuel/library/active_record/update.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require_relative 'base'
+
+module DbFuel
+  module Library
+    module ActiveRecord
+      # This job can take the objects in a register and updates them within database table.
+      # The attributes translate to SQL SET clauses and the unique_keys translate to
+      # WHERE clauses.
+      #
+      # Expected Payload[register] input: array of objects
+      # Payload[register] output: array of objects.
+      class Update < Base
+        attr_reader :unique_keys
+
+        # Arguments:
+        #   name [required]: name of the job within the Burner::Pipeline.
+        #
+        #   table_name [required]: name of the table to use for the INSERT statements.
+        #
+        #   attributes:  Used to specify which object properties to put into the
+        #                SQL statement and also allows for one last custom transformation
+        #                pipeline, in case the data calls for sql-specific transformers
+        #                before mutation.
+        #
+        #   debug: If debug is set to true (defaults to false) then the SQL statements and
+        #          returned objects will be printed in the output.  Only use this option while
+        #          debugging issues as it will fill up the output with (potentially too much) data.
+        #
+        #   separator: Just like other jobs with a 'separator' option, if the objects require
+        #              key-path notation or nested object support, you can set the separator
+        #              to something non-blank (like a period for notation in the
+        #              form of: name.first).
+        #
+        #   timestamps: If timestamps is true (default behavior) then the updated_at column will
+        #               automatically have its value set to the current UTC timestamp.
+        #
+        #   unique_keys: Each key will become a WHERE clause in order to only update specific
+        #                records.
+        def initialize(
+          name:,
+          table_name:,
+          attributes: [],
+          debug: false,
+          register: Burner::DEFAULT_REGISTER,
+          separator: '',
+          timestamps: true,
+          unique_keys: []
+        )
+          explicit_attributes = Burner::Modeling::Attribute.array(attributes)
+
+          attributes = timestamps ? timestamp_attributes + explicit_attributes : explicit_attributes
+
+          super(
+            name: name,
+            table_name: table_name,
+            attributes: attributes,
+            debug: debug,
+            register: register,
+            separator: separator
+          )
+
+          @unique_keys = Modeling::KeyedColumn.array(unique_keys)
+
+          freeze
+        end
+
+        def perform(output, payload)
+          total_rows_affected = 0
+
+          payload[register] = array(payload[register])
+
+          payload[register].each do |row|
+            update_manager = make_update_manager(row, payload.time)
+
+            debug_detail(output, "Update Statement: #{update_manager.to_sql}")
+
+            rows_affected = ::ActiveRecord::Base.connection.update(update_manager)
+
+            debug_detail(output, "Individual Rows Affected: #{rows_affected}")
+
+            total_rows_affected += rows_affected
+          end
+
+          output.detail("Total Rows Affected: #{total_rows_affected}")
+        end
+
+        private
+
+        def make_update_manager(row, time)
+          arel_row       = make_arel_row(transform(row, time))
+          unique_values  = make_unique_column_values(row)
+          update_manager = ::Arel::UpdateManager.new.set(arel_row).table(arel_table)
+
+          apply_where(unique_values, update_manager)
+        end
+
+        def make_unique_column_values(row)
+          unique_keys.each_with_object({}) do |unique_key, memo|
+            memo[unique_key.column] = resolver.get(row, unique_key.key)
+          end
+        end
+
+        def apply_where(hash, manager)
+          (hash || {}).inject(manager) do |memo, (key, value)|
+            memo.where(arel_table[key].eq(value))
+          end
+        end
+
+        def timestamp_attributes
+          [timestamp_attribute(UPDATED_AT)]
+        end
+      end
+    end
+  end
+end

data/lib/db_fuel/modeling.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require_relative 'modeling/keyed_column'

data/lib/db_fuel/modeling/keyed_column.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module DbFuel
+  module Modeling
+    # Connects a hash key to a sql column.  By default if a column is not given then its
+    # key will be used for both.  The general use case for this is for mapping objects
+    # to sql and sql to objects.
+    class KeyedColumn
+      acts_as_hashable
+
+      attr_reader :column, :key
+
+      def initialize(key:, column: '')
+        raise ArgumentError, 'key is required' if key.blank?
+
+        @column = column.present? ? column.to_s : key.to_s
+        @key    = key.to_s
+
+        freeze
+      end
+    end
+  end
+end

data/lib/db_fuel/version.rb

@@ -8,5 +8,5 @@
 #
 
 module DbFuel
-  VERSION = '1.0.0'
+  VERSION = '1.1.0-alpha'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: db_fuel
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0.pre.alpha
 platform: ruby
 authors:
 - Matthew Ruggio
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-11-18 00:00:00.000000000 Z
+date: 2020-11-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -50,14 +50,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: dbee
   requirement: !ruby/object:Gem::Requirement
@@ -237,9 +237,14 @@ files:
 - exe/.gitkeep
 - lib/db_fuel.rb
 - lib/db_fuel/library.rb
+- lib/db_fuel/library/active_record/base.rb
+- lib/db_fuel/library/active_record/insert.rb
+- lib/db_fuel/library/active_record/update.rb
 - lib/db_fuel/library/dbee/base.rb
 - lib/db_fuel/library/dbee/query.rb
 - lib/db_fuel/library/dbee/range.rb
+- lib/db_fuel/modeling.rb
+- lib/db_fuel/modeling/keyed_column.rb
 - lib/db_fuel/version.rb
 homepage: https://github.com/bluemarblepayroll/db_fuel
 licenses:
@@ -261,9 +266,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.0.3
 signing_key: