db2_query 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fde277f004b8ff05460621968ce473c7f15f047a5903e77c6bf7da997640d8dc
-  data.tar.gz: 72fc3599f00909fabc2125964ce5a3f79de9e2343577937206c04c88d7b97cc1
+  metadata.gz: a62d60225cd34e421f6d6fd8becf1d45bb6e0ffb35db266bac881734a4b15340
+  data.tar.gz: 8b02f4869439de1dcdb14cfca0f731ee99ce143f504b6a56c7e04db74684da65
 SHA512:
-  metadata.gz: 477d63287ce0a745ba5dfd91c82f8984632976dec003c305f5a888ba54bccec8b5b8a065c12462bb2294dc14f74537d135ed012df9a0a541cb773109c22a6ff9
-  data.tar.gz: ab481810cc3cb1ed79bb97594d3af8480e518e7527d770d73606523b5ae35504a4bb6b0ef128ee32f579216604a6b1e43e6230e6e0b0e4fc222a005e086cc513
+  metadata.gz: a684c13ff35469b6f53c13b0bcd2c21c997b9b51abce517bc66ca920a4cc764ae885a1746b1e256d50945cc038d240739c8de72045b899af6e63421b8a520c24
+  data.tar.gz: a2698708b312200a55f93334c5f27b5345f9b0515a6ca8aee82926562388178588766bb708959178f26488774a3994a5e88f2181691e8604f9d7ac6f62a2dcfb

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2020 yohanes_l
+Copyright 2021 yohanes oktavianus lumentut
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -2,7 +2,9 @@
 
 [![Gem Version](https://badge.fury.io/rb/db2_query.svg)](https://badge.fury.io/rb/db2_query)
 
-A Rails query plugin to fetch data from Db2 database by using ODBC connection.
+A Rails 5 & Rails 6 plugin for handling Db2 SQL database `SIUD` statement (`SELECT`, `INSERT`, `UPDATE`, `DELETE`) by using ODBC connection.
+
+Note: Tested at Rails 5.2.6 and Rails 6.1.4
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -26,82 +28,186 @@ Execute init task at the app root
 ```bash
 $ rake db2query:init
 ```
-DB2Query will generate two required files:
-- `config/db2query_database.yml`
-- `config/initializers/db2query`
+Db2Query will generate two required files:
+- `config/db2query.yml`
+- `config/initializers/db2query.rb`
 
-Edit these files according to the requirement.
+Edit those files according to the requirement.
 
 ### Database Configuration
-At `db2query_database.yml` we can use two type of connection:
-1. DSN connection config
-2. Connection String config
+At version 0.3.0, `db2query.yml` only use DSN connection config:
 ```yml
-development:
-  primary:                          # Connection String Example
-    adapter: db2_query
-    conn_string:
-      driver: DB2
-      database: SAMPLE
-      dbalias: SAMPLE
-      hostname: LOCALHOST
-      currentschema: LIBTEST
-      port: "0"
-      protocol: IPC
-      uid: <%= ENV["DB2EC_UID"] %>
-      pwd: <%= ENV["DB2EC_PWD"] %>
-  secondary:
-    adapter: db2_query             # DSN Example
-    dsn: iseries
-    uid: <%= ENV["ISERIES_UID"] %>
-    pwd: <%= ENV["ISERIES_PWD"] %>
+  development:
+     dsn: ARUNIT
+     idle: 5
+     pool: 5
+     timeout: 5
+  test:
+     dsn: ARUNIT
+     idle: 5
+     pool: 5
+     timeout: 5
+  production:
+     dsn: ARUNIT
+     idle: 5
+     pool: 5
+     timeout: 5
+```
+
+Note: `idle` is a `db_client` idle maximum limit value (in minutes) to avoid the client disconnected by the host server. Setting this value to zero will lead to an "ODBC driver Communication Link Failure. Comm rc 10054 . [CWBCO1047](https://www.ibm.com/support/pages/cwbco1047-any-function-uses-database-host-server)" error after a certain period of time.
+
+Ensure that `unixodbc` have been installed and test your connection first by using `isql` commands.
+
+Example:
+
+ARUNIT DSN connection test
+```bash
+$ isql -v ARUNIT
++---------------------------------------+
+| Connected!                            |
+|                                       |
+| sql-statement                         |
+| help [tablename]                      |
+| quit                                  |
+|                                       |
++---------------------------------------+
+SQL> 
 ```
 
 ## Usage
+Note: Version 0.1.0 use `Db2Query` namespace. Version 0.2 use `DB2Query`. At version 0.3.0 we use `Db2Query`  , revert back to the previous namespace.
+
 ### Basic Usage
-Create query class that inherit from `DB2Query::Base` in `app/queries` folder
+Create query class that inherit from `DB2Query::Base` in `app/queries` folder. 
+
+Note: `$`symbol is used as column name prefix.
+
+### 1. `query` method
+The `query` method must have 2 inputs:
+1. Method name
+2. Body (can be an SQL statement or lamda).
+
+The lambda is used to facilitate us in using `built-in methods` as shown at examples below:
+
+Example 1.
 ```ruby
-class User < DB2Query::Base
+class User < Db2Query::Base
   query :find_by, <<-SQL
-    SELECT * FROM LIBTEST.USERS WHERE id = ?
+    SELECT * FROM LIBTEST.USERS WHERE $id = ?
   SQL
 end
 ```
-Or use a normal sql method (don't forget the `_sql` suffix)
+```bash
+irb(main):004:0> User.find_by 10000
+  SQL (3.2ms)  SELECT * FROM LIBTEST.USERS WHERE id = ?  [["id", 10000]]
+=> #<DB2Query::Result @records=[#<Record id: 10000, first_name: "Strange", last_name: "Stephen", email: "strange@marvel.universe.com">]>
+```
+Example 2.
 ```ruby
-class User < DB2Query::Base 
+class User < Db2query::Base
+  query :id_greater_than, -> id {
+    exec_query({}, "SELECT * FROM LIBTEST.USERS WHERE $id > ?", [id])
+  }
+end
+```
+```bash
+irb(main):003:0> User.id_greater_than 10000
+  SQL (3.2ms)  SELECT * FROM LIBTEST.USERS WHERE id > ?  [["id", 1000]]
+=> #<Db2Query::Result [#<Record id: 10000, first_name: "Strange", last_name: "Stephen", email: "strange@marvel.universe.com">...">]>
+```
+Example 3.
+```ruby
+class User < Db2query::Base
+  query :insert_record, -> args {
+    exec_query({},
+      "INSERT INTO users ($id, $first_name, $last_name, $email) VALUES (?, ?, ?, ?)", args
+  )
+}
+end
+```
+```bash
+irb(main):002:0> User.insert_record [77777, "Ancient", "One", "ancientone@marvel.universe.com"]
+  SQL (3651.2ms)  SELECT * FROM NEW TABLE (INSERT INTO users (id, first_name, last_name, email) VALUES (?, ?, ?, ?))  [["id,", 77777], ["first_name,", "Ancient"], ["last_name,", "One"], ["email)", "ancientone@marvel.universe.com"]]
+=> #<Db2Query::Result [#<Record id: 77777, first_name: "Ancient", last_name: "One", email: "ancientone@marvel.universe.com">]>
+```
+
+### 2. Plain/normal method
+At a plain/normal sql method we add `_sql` suffix. For example `find_by_sql`
+```ruby
+class User < Db2Query::Base 
   def find_by_sql
-    "SELECT * FROM LIBTEST.USERS WHERE id = ?"
+    "SELECT * FROM LIBTEST.USERS WHERE $id = ?"
   end
 end
 ```
-Check it at rails console
+Then we can call it by using `find_by` class method.
 ```bash
-User.find_by 10000
-SQL Load (3.28ms)  SELECT * FROM LIBTEST.USERS WHERE user_id = ? [[nil, 10000]]
+irb(main):001:0> User.find_by 10000
+SQL Load (3.28ms)  SELECT * FROM LIBTEST.USERS WHERE id = ? [["id", 10000]]
 => #<DB2Query::Result @records=[#<Record id: 10000, first_name: "Strange", last_name: "Stephen", email: "strange@marvel.universe.com">]>
 ```
-Or using keywords argument
+Or with hash arguments input
+```ruby
+class User < Db2Query::Base
+  def by_name_and_email_sql
+    "SELECT * FROM LIBTEST.USERS WHERE $first_name = ? AND $email = ?"
+  end
+end
+```
 ```bash
-User.by_name first_name: "Strange", last_name: "Stephen"
-SQL Load (3.28ms)  SELECT * FROM LIBTEST.USERS WHERE first_name = ? AND last_name = ? [["first_name", Strange], ["last_name", Stephen]]
+irb(main):001:0> User.by_name_and_email first_name: "Strange", email: "strange@marvel.universe.com"
+SQL Load (3.28ms)  SELECT * FROM LIBTEST.USERS WHERE first_name = ? AND last_name = ? [["first_name", Strange], ["email", strange@marvel.universe.com]]
 => #<DB2Query::Result @records=[#<Record id: 10000, first_name: "Strange", last_name: "Stephen", email: "strange@marvel.universe.com">]>
+```
+###  SQL extention (`@extention`)
+For a reusable sql, we can extend it by using a combination of `extention` and `sql_with_extention` methods,  with an `@extention` pointer at SQL statement.
+```ruby
+class User < Db2Query::Base
+  # reusable SQL
+  _SQL = -> extention {
+    sql_with_extention("SELECT * FROM LIBTEST.USERS WHERE @extention", extention)
+  }
+  
+  # implementation
+  query :by_email, _SQL.("$email = ?")
+end
+```
+```bash
+irb(main):004:0> User.by_email "strange@marvel.universe.com"
+  SQL (3.2ms)  SELECT * FROM LIBTEST.USERS WHERE email = ?  [["email", "strange@marvel.universe.com"]]
+=> #<DB2Query::Result @records=[#<Record id: 10000, first_name: "Strange", last_name: "Stephen", email: "strange@marvel.universe.com">]> 
+```
+### List input (`@list`)
+For an array consist list of inputs, we can use `fetch_list` method and `@list` pointer at the SQL statement.
+
+```ruby
+class User < Db2Query
+  query :by_ids, -> ids {
+    fetch_list("SELECT * FROM LIBTEST.USERS WHERE ID IN (@list)", ids)
+  }
+end
+```
+```bash
+irb(main):007:0> User.by_ids [10000,10001,10002]
+  SQL (2.8ms)  SELECT * FROM LIBTEST.USERS WHERE ID IN ('10000', '10001', '10002')
+=> #<Db2Query::Result [#<Record id: 10000, name: "Carol", last_name: "Danvers", email: "captain.marvel@marvel.universe.com">, #<Record id: 10001, first_name: "Natasha", last_name: "Romanova", email: "black.widow@marvel.universe">, #<Record id: 10002, first_name: "Wanda", last_name: "Maximoff", email: "scarlet.witch@marvel.universe.com">]>
+
 ```
 
 ### Formatter
-In order to get different result column format, a query result can be reformatted by add a formatter class that inherit `DB2Query::AbstractFormatter` then register at `config\initializers\db2query.rb`
+In order to get different result column format, a query result can be reformatted by adding a formatter class that inherits `DB2Query::AbstractFormatter` then register at `config\initializers\db2query.rb`
 ```ruby
 require "db2_query/formatter"
 
 # create a formatter class
-class FirstNameFormatter < DB2Query::AbstractFormatter
+class FirstNameFormatter < Db2Query::AbstractFormatter
   def format(value)
     "Dr." + value
   end
 end
 
 # register the formatter class
-DB2Query::Formatter.registration do |format|
+Db2Query::Formatter.registration do |format|
   format.register(:first_name_formatter, FirstNameFormatter)
 end
 ```
@@ -114,12 +220,69 @@ end
 Check it at rails console
 ```bash
 Doctor.find_by id: 10000
-SQL Load (30.28ms)  SELECT * FROM LIBTEST.USERS WHERE user_id = ? [["id", 10000]]
+SQL Load (3.28ms)  SELECT * FROM LIBTEST.USERS WHERE id = ? [["id", 10000]]
 => #<DB2Query::Result @records=[#<Record id: 10000, first_name: "Dr.Strange", last_name: "Stephen", email: "strange@marvel.universe.com">]>
 ```
 
-### Available methods
-`DB2Query::Result` inherit all `ActiveRecord::Result` methods with additional custom `records` method.
+For complete examples please see the basic examples [here](https://github.com/yohaneslumentut/db2_query/blob/master/test/dummy/app/queries/test_query.rb).
+
+### Available Result Object methods
+`Db2Query::Result` inherit all `ActiveRecord::Result` methods with additional custom methods:
+  1. `records` to convert query result into array of Record objects.
+  2. `to_h` to convert query result into hash with symbolized keys.
+
+### Built-in methods
+These built-in methods are delegated to `Db2Query::Connection` methods
+  1. `query_rows(sql)`
+  2. `query_value(sql)`
+  3. `query_values(sql)`
+  4. `execute(sql)`
+  5. `exec_query(formatters, sql, args = [])`
+They behave just likely `ActiveRecords` connection's public methods.
+
+### ActiveRecord Combination
+
+Create an abstract class that inherit from `ActiveRecord::Base`
+```ruby
+class Db2Record < ActiveRecord::Base
+  self.abstract_class = true
+
+  def self.query(formatter, sql, args = [])
+    Db2Query::Base.connection.exec_query(formatter, sql, args).to_a.map(&:deep_symbolize_keys)
+  end
+end
+```
+
+Utilize the goodness of rails model `scope`
+```ruby
+class User < Db2Record
+  scope :by_name, -> *args {
+    query(
+      {}, "SELECT * FROM LIBTEST.USERS WHERE $first_name = ? AND $last_name = ?", args
+    )
+  }
+end
+```
+```bash
+User.by_name first_name: "Strange", last_name: "Stephen"
+SQL Load (3.28ms)  SELECT * FROM LIBTEST.USERS WHERE first_name = ? AND last_name = ? [["first_name", Strange], ["last_name", Stephen]]
+=> [{:id=> 10000, :first_name=> "Strange", :last_name=> "Stephen", :email=> "strange@marvel.universe.com"}]
+```
+
+Another example:
+```ruby
+class User < Db2Record
+  scope :age_gt, -> age {
+    query("SELECT * FROM LIBTEST.USERS WHERE age > #{age}")
+  }
+end
+```
+
+```bash
+User.age_gt 500
+SQL Load (3.28ms)  SELECT * FROM LIBTEST.USERS WHERE age > 500
+=> [{:id=> 99999, :first_name=> "Ancient", :last_name=> "One", :email=> "ancientone@marvel.universe.com"}]
+```
 
 ## License
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
+require "bundler/setup"
 require "bundler/gem_tasks"
 require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
 end
 
 task default: :test

data/lib/db2_query.rb

@@ -1,23 +1,22 @@
-# frozen_string_literal:true
+# frozen_string_literal: true
 
-require "yaml"
-require "erb"
 require "active_record"
 require "active_support"
-require "active_record/database_configurations"
-require "db2_query/config"
+require "active_support/concurrency/load_interlock_aware_monitor"
+require "connection_pool"
+require "odbc_utf8"
 
-module DB2Query
+module Db2Query
   extend ActiveSupport::Autoload
 
   autoload :Version
-  autoload :Base
+  autoload :Config
+  autoload :Connection
   autoload :Core
-  autoload :ConnectionHandling
-  autoload :DatabaseStatements
-  autoload :ODBCConnector
-  autoload :Formatter
   autoload :Result
+  autoload :Logger
+  autoload :Error
+  autoload :Base
 
   require "db2_query/railtie" if defined?(Rails)
 end

data/lib/db2_query/base.rb

@@ -1,11 +1,8 @@
 # frozen_string_literal: true
 
-module DB2Query
+module Db2Query
   class Base
-    include DB2Query::Core
-    include ActiveRecord::Inheritance
-    extend ActiveSupport::Concern
-    extend ActiveRecord::ConnectionHandling
-    extend DB2Query::ConnectionHandling
+    include Config
+    include Core
   end
 end

data/lib/db2_query/config.rb

@@ -1,30 +1,29 @@
 # frozen_string_literal: true
 
-module DB2Query
-  class << self
-    def config
-      @config ||= read_config
-    end
-
-    def config_path
-      if defined?(Rails)
-        "#{Rails.root}/config/db2query_database.yml"
-      else
-        ENV["DQ_CONFIG_PATH"]
-      end
-    end
+module Db2Query
+  module Config
+    extend ActiveSupport::Concern
+    DEFAULT_ENV = -> { (Rails.env if defined?(Rails.env)) || ENV["RAILS_ENV"].presence }
 
-    def config_file
-      Pathname.new(config_path)
+    included do
+      @@configurations = nil
     end
 
-    def read_config
-      erb = ERB.new(config_file.read)
-      YAML.parse(erb.result(binding)).transform
-    end
+    class_methods do
+      def configurations
+        @@configurations
+      end
+      alias config configurations
 
-    def connection_env
-      ENV["RAILS_ENV"].to_sym
+      def load_database_configurations(path = nil)
+        file_path = path || "#{Rails.root}/config/db2query.yml"
+        if File.exist?(file_path)
+          config_file = IO.read(file_path)
+          @@configurations = YAML.load(config_file)[DEFAULT_ENV.call].transform_keys(&:to_sym)
+        else
+          raise Db2Query::Error, "Could not load db2query database configuration. No such file - #{file_path}"
+        end
+      end
     end
   end
 end