db2_query 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d2946448234d56484778d59e3051573c81c2789631776f0ed543a79fdc510fa
-  data.tar.gz: a257fabf1a7de500f7d325c70dd11f494a08163dbf78460f61b3bf51cb626b77
+  metadata.gz: '09ecde3a8404d9aa56b416cbd3aa89efb21519166dea225cf8e3d7a54a2b4ed1'
+  data.tar.gz: c72fe3cc5e681d99d3dd5a6ec85863cb15b4b95e72b92e42dcb9d20fac910fbc
 SHA512:
-  metadata.gz: ca8c1b52138ec97d9f4e9cbbca0d8bb148e95f4ac181a929e3e5715b597ed59b70e25b779156ba45a7fe9f119203e4162a2a932c63d11c94acdc2a1eaeb56db8
-  data.tar.gz: 67f0d7228274d4a7a6e38771cc0743b83da27621d3ce310e0d5d7d323e937316f700ec3b278734312ff27cdc88796321cb09f02d7c2bf48b8c5607a7331a7f27
+  metadata.gz: 20370e437967f91a7b273b21339c22ad4f868310812be5ff40676eb0ae28044def876276044aa1a0f237fec1b47e3acf6b7591e2bf1d76d53b7876ca688528ae
+  data.tar.gz: aa62b2ff0df74fb300963ab83c36f066b6e032d26de149ade42ed7cd79daac5579aedeae1bafd264747466a0719520b76ef8cef49e7e1e4c64a9cc84eb9f46db

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

@@ -1,5 +1,10 @@
-# Db2Query
-A Rails query plugin to fetch data from Db2 database by using ODBC connection.
+# DB2Query
+
+[![Gem Version](https://badge.fury.io/rb/db2_query.svg)](https://badge.fury.io/rb/db2_query)
+
+A Rails 5 & Rails 6 plugin for handling Db2 SQL database `SIUD` statement (`SELECT`, `INPUT`, `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:
@@ -15,7 +20,7 @@ $ bundle
 
 Or install it yourself as:
 ```bash
-$ gem install db2-query
+$ gem install db2_query
 ```
 
 ## Initialization
@@ -24,67 +29,170 @@ Execute init task at the app root
 $ rake db2query:init
 ```
 Db2Query will generate two required files:
-- `config/db2query_database.yml`
-- `config/initializers/db2query`
+- `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
-    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:                       # DSN Example
-    dsn: SAMPLE
-    uid: <%= ENV["DB2EC_UID"] %>
-    pwd: <%= ENV["DB2EC_PWD"] %>
+  development:
+     dsn: ARUNIT
+     pool: 5
+     timeout: 5
+  test:
+     dsn: ARUNIT
+     pool: 5
+     timeout: 5
+  production:
+     dsn: ARUNIT
+     pool: 5
+     timeout: 5
+```
+
+Ensure that `unixodbc` have been installed and test your connection first by using `isql` commands.
+
+Example:
+
+Secondary database 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 two query methods below:
+Example 1.
 ```ruby
-class Users < Db2Query::Base
+class User < Db2Query::Base
   query :find_by, <<-SQL
-    SELECT * FROM LIBTEST.USERS WHERE user_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 [#<Record id: 10000, first_name: "Wilma", last_name: "Lindgren", email: "cleveland_kilback@breitenberg.com">]>
+```
+Example 2.
 ```ruby
-class Users < 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: "Wilma", last_name: "Lindgren", email: "cleveland_kilback@breitenberg.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
+```
+
+### 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 user_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
+irb(main):001:0> User.find_by 10000
+SQL Load (3.28ms)  SELECT * FROM LIBTEST.USERS WHERE id = ? [[nil, 10000]]
+=> #<DB2Query::Result @records=[#<Record id: 10000, first_name: "Strange", last_name: "Stephen", email: "strange@marvel.universe.com">]>
+```
+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
+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
-Users.find_by 10000
-Users Load (330.28ms)  SELECT * FROM LIBTEST.USERS WHERE user_id = ? [[10000]]
-=> #<Db2Query::Result [#<Users::FindBy user_id: 10000, first_name: "Alex", last_name: "Jacobi", email: "lula_durgan@dooley.com">]>
+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
   def format(value)
-    "Mr/Mrs. " + value
+    "Dr." + value
   end
 end
 
@@ -95,30 +203,76 @@ end
 ```
 Use it at query class
 ```ruby
-class Users < Db2Query::Base
+class Doctor < User
   attributes :first_name, :first_name_formatter
-
-  query :find_by, <<-SQL
-    SELECT * FROM LIBTEST.USERS WHERE user_id = ?
-  SQL
 end
 ```
 Check it at rails console
 ```bash
-Users.find_by 10000
-Users Load (330.28ms)  SELECT * FROM LIBTEST.USERS WHERE user_id = ? [[10000]]
-=> #<Db2Query::Result [#<Users::FindBy user_id: 10000, first_name: "Mr/Mrs. Alex", last_name: "Jacobi", email: "lula_durgan@dooley.com">]>
+Doctor.find_by 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 has public methods as follows:
-- to_a
-- to_hash
-- pluck
-- first
-- last
-- size
-- each
 
+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,23 +1,7 @@
 # frozen_string_literal: true
 
-begin
-  require "bundler/setup"
-rescue LoadError
-  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
-end
-
-require "rdoc/task"
-
-RDoc::Task.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = "rdoc"
-  rdoc.title    = "Db2Query"
-  rdoc.options << "--line-numbers"
-  rdoc.rdoc_files.include("README.md")
-  rdoc.rdoc_files.include("lib/**/*.rb")
-end
-
+require "bundler/setup"
 require "bundler/gem_tasks"
-
 require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|

data/lib/db2_query.rb

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

data/lib/db2_query/base.rb

@@ -2,83 +2,7 @@
 
 module Db2Query
   class Base
-    include DatabaseConfigurations
-    include ConnectionHandling
-
-    class << self
-      include SQLValidator
-
-      def attributes(attr_name, format)
-        attr_format.store(attr_name, format)
-      end
-
-      def query(method_name, sql_statement)
-        unless is_query?(sql_statement)
-          raise Error, "Query only for SQL query commands."
-        end
-
-        if self.class.respond_to?(method_name)
-          raise Error, "Query :#{method_name} has been defined before"
-        end
-
-        self.class.define_method(method_name) do |*args|
-          log(sql_statement, args) do
-            columns, rows = connection.exec_query(sql_statement, *args)
-            Result.new(self, method_name, columns, rows, attr_format)
-          end
-        end
-      end
-
-      private
-        def attr_format
-          @attr_format ||= Hash.new
-        end
-
-        def define_query_method(method_name, sql_statement)
-          if is_query?(sql_statement)
-            query(method_name, sql_statement)
-          else
-            raise NotImplementedError
-          end
-        end
-
-        def method_missing(method_name, *args, &block)
-          sql_methods = self.instance_methods.grep(/_sql/)
-          sql_method = "#{method_name}_sql".to_sym
-
-          if sql_methods.include?(sql_method)
-            sql_statement = allocate.method(sql_method).call
-
-            raise Error, "Query methods must return a SQL statement string!" unless sql_statement.is_a? String
-
-            expected_args = sql_statement.count "?"
-            given_args = args.size
-
-            if expected_args == given_args
-              define_query_method(method_name, sql_statement)
-            else
-              raise ArgumentError, "wrong number of arguments (given #{given_args}, expected #{expected_args})"
-            end
-
-            method(method_name).call(*args)
-          else
-            super
-          end
-        end
-
-        def instrumenter
-          @instrumenter ||= ActiveSupport::Notifications.instrumenter
-        end
-
-        def log(sql_statement, args)
-          instrumenter.instrument(
-            "sql.db2_query",
-            sql:   sql_statement,
-            name:  self,
-            binds: args) do
-            yield
-          end
-        end
-    end
+    include Config
+    include Core
   end
 end