wikk_sql 0.1.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 1b44f3220ce0dfd76001f10d0050068bc5c78351
-  data.tar.gz: '08f7b039eca6733f51882fa48b820107a6ae81ea'
+SHA256:
+  metadata.gz: 69f45ee6d7fb4c55391f5f0dcbb161b1abaa53a57fa6a845223e0293d356d622
+  data.tar.gz: e057cd23694695352a95f6d2b7ec72cd3216b22456c0ed73646a0d742bfa74a2
 SHA512:
-  metadata.gz: 8792cdf2b2247da43c528d5376656aae88d56ae494cf02bc13c10a7ad52363839f7eaf194728325081e0444a116c8aa7c9551e2da163116001ce257bb657e1bb
-  data.tar.gz: e0136313a530dd3a4cded3c3bd8f890e0507491a3c9bfbba71c28e0f8786525990b3766397123d2723602012d4413a11b96787c9890672a9b8a8582204c70143
+  metadata.gz: 388b183d0bf33873a8fa840a55016000a1d66d36d64dc65028dd219857e67dac0e9ec560a786bce4c0bc7d7d2d7f2561b8e3b22121ada356e91cd0761e00a8b3
+  data.tar.gz: 85e177dda64b58d5319db994f3fadb94ae2f0d3eb9ba0a6ba6aced0c2de0344311c199752614f36b0783641651a3eb9d434777c5402cda51a26bd41d4102b017

data/History.txt

@@ -1,3 +1,81 @@
+robertburrowes	Tue Jun 21 09:26:47 2022 +1200
+	bump version
+robertburrowes	Tue Jun 21 09:26:16 2022 +1200
+	add aliases, so calls without blocks read better
+robertburrowes	Sun Jun 5 14:16:58 2022 +1200
+	Split gem into a loader, and connector files
+robertburrowes	Sun Jun 5 14:00:56 2022 +1200
+	add escape()
+robertburrowes	Fri Jun 3 11:35:39 2022 +1200
+	Add self.escape
+robertburrowes	Thu Jun 2 16:29:38 2022 +1200
+	test cleanup.
+robertburrowes	Thu Jun 2 16:23:33 2022 +1200
+	Hashed_row should have been hrow
+robertburrowes	Thu Jun 2 16:13:17 2022 +1200
+	Added each_param (**kwargs) test, and changed each_sym test to not use params
+robertburrowes	Thu Jun 2 16:07:24 2022 +1200
+	Uppercased user rather than DB
+robertburrowes	Thu Jun 2 16:07:10 2022 +1200
+	add escape method
+robertburrowes	Thu Jun 2 15:47:21 2022 +1200
+	Test DB uppercase
+robertburrowes	Wed Jun 1 14:17:39 2022 +1200
+	Now need a each_param, as hash to named kargs now needs a **
+robertburrowes	Tue May 31 22:03:20 2022 +1200
+	name change
+robertburrowes	Tue May 31 22:03:08 2022 +1200
+	Wrong exception
+robertburrowes	Tue May 31 22:02:51 2022 +1200
+	Setting up test DB
+robertburrowes	Tue May 31 18:44:38 2022 +1200
+	Merge branch 'master' of github.com:wikarekare/wikk_sql
+robertburrowes	Tue May 31 17:04:27 2022 +1200
+	Working on consistency between ruby-mysql and mysql2 connectors
+robertburrowes	Tue May 31 17:03:55 2022 +1200
+	unsure we get bash
+robertburrowes	Tue May 31 17:00:43 2022 +1200
+	rubocop'd
+robertburrowes	Thu May 26 22:42:58 2022 +1200
+	Getting it to work, Slowly
+robertburrowes	Thu May 26 16:55:35 2022 +1200
+	Working towards having the gem work with either ruby-mysql or mysql2
+robertburrowes	Mon May 23 20:36:26 2022 +1200
+	rubocop'd
+robertburrowes	Sun Oct 25 21:44:30 2020 +1300
+	Yard comment tidy up
+robertburrowes	Sun Oct 25 21:15:26 2020 +1300
+	Fix doc url
+robertburrowes	Sun Oct 25 21:14:28 2020 +1300
+	mode change
+robertburrowes	Sun Oct 25 21:14:19 2020 +1300
+	Update for new Hoe
+robertburrowes	Sun Oct 25 21:13:58 2020 +1300
+	Improve dependency to remove warning
+robertburrowes	Sun Oct 25 21:13:40 2020 +1300
+	Include in repo
+robertburrowes	Sun Oct 25 21:13:26 2020 +1300
+	mv dev scripts to sbin
+robertburrowes	Thu Jun 29 10:13:40 2017 +1200
+	raise exception if not connected
+robertburrowes	Thu Jun 29 09:43:14 2017 +1200
+	result should have been @result
+robertburrowes	Wed Jan 4 16:49:28 2017 +1300
+	set @affected_rows before query :(
+robertburrowes	Tue Jun 28 22:39:37 2016 +1200
+	added auto git tagging on release
+robertburrowes	Sun Jun 19 14:58:57 2016 +1200
+	Put Wikk Configuration class into module WIKK
+robertburrowes	Sun Jun 19 14:54:48 2016 +1200
+	Acknowledge code origin
+robertburrowes	Sun Jun 19 14:50:56 2016 +1200
+	Tidied up inline documentation of class
+robertburrowes	Sun Jun 19 14:50:30 2016 +1200
+	Ensured history file generated before package is generated
+robertburrowes	Sun Jun 19 14:50:07 2016 +1200
+	Upped version
+robertburrowes	Sun Jun 19 14:49:52 2016 +1200
+	Changed WIKK_SQL to module WIKK::SQL
 robertburrowes	Sun Jun 19 14:01:08 2016 +1200
 	Encapsulation of SQL into module WIKK
 robertburrowes	Sun Jun 19 13:59:27 2016 +1200

data/Manifest.txt

@@ -3,3 +3,5 @@ Manifest.txt
 README.md
 Rakefile
 lib/wikk_sql.rb
+lib/wikk_ruby_mysql.rb
+lib/wikk_mysql2.rb

data/README.md

@@ -1,8 +1,8 @@
 # wikk_sql
 
-* http://rbur004.github.com/wikk_sql/
-* Source https://github.com/wikarekare/wikk_sql
-* Gem https://rubygems.org/gems/wikk_sql
+* Docs :: https://wikarekare.github.io/wikk_sql/
+* Source :: https://github.com/wikarekare/wikk_sql
+* Gem :: https://rubygems.org/gems/wikk_sql
 
 ## DESCRIPTION:
 

data/Rakefile

@@ -1,27 +1,27 @@
 # -*- ruby -*-
-
 require 'rubygems'
 require 'hoe'
 Hoe.plugin :yard
 
-Hoe.spec 'wikk_sql' do 
-  self.readme_file = "README.md"
-  self.developer( "Rob Burrowes","r.burrowes@auckland.ac.nz")
+Hoe.spec 'wikk_sql' do
+  self.readme_file = 'README.md'
+  self.developer( 'Rob Burrowes', 'r.burrowes@auckland.ac.nz')
   remote_rdoc_dir = '' # Release to root
-  
+
   self.yard_title = 'wikk_sql'
-  self.yard_options = ['--markup', 'markdown', '--protected']
-end
+  self.yard_options = [ '--markup', 'markdown', '--protected' ]
 
+  #  self.dependency "ruby-mysql", ['~> 1.0', '>= 1.0.0']
+end
 
-#Validate manfest.txt
-#rake check_manifest
+# Validate manfest.txt
+# rake check_manifest
 
-#Local checking. Creates pkg/
-#rake gem
+# Local checking. Creates pkg/
+# rake gem
 
-#create doc/
-#rake docs  
+# create doc/
+# rake docs
 
-#Copy up to rubygem.org
-#rake release VERSION=1.0.1
+# Copy up to rubygem.org
+# rake release VERSION=1.0.1

data/lib/wikk_mysql2.rb

@@ -0,0 +1,384 @@
+require 'mysql2'
+
+# Provides common front end, even if we change the connector library
+# Connector is mysql2. Requires libmysql-dev or libmariadb-dev to install the gem.
+module WIKK
+  # WIKK_SQL wrapper for ruby mysql gem.
+  # @attr_reader [Numeric] affected_rows the number of rows changed, deleted, or added.
+  # @attr_reader [Mysql::Result] result the last query's result
+  # @attr_reader [Mysql] my the DB connection descriptor
+  class SQL
+    attr_reader :affected_rows, :result, :my
+
+    # Create WIKK::SQL instance and set up the mySQL connection.
+    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
+    # @yieldparam sql [WIKK_SQL] if a block is given.
+    # @return [NilClass] if block is given, and closes the mySQL connection.
+    # @return [WIKK_SQL] if no block is given, and caller must call sql.close
+    def self.connect(db_config)
+      sql = self.new
+      sql.connect(db_config)
+      if block_given?
+        yield sql
+        return sql.close
+      else
+        return sql
+      end
+    end
+
+    # Set up the mySQL connection.
+    #
+    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
+    # @yieldparam [] if a block is given.
+    # @return [NilClass] if block is given, and closes the mySQL connection.
+    # @return [WIKK_SQL] if no block is given, and caller must call sql.close
+    def connect(db_config)
+      if db_config.instance_of?(Hash)
+        sym = db_config.transform_keys(& :to_sym )
+        db_config = Struct.new(*(k = sym.keys)).new(*sym.values_at(*k))
+      end
+
+      begin
+        @my = Mysql2::Client.new( host: db_config.host,
+                                  database: db_config.db,
+                                  username: db_config.dbuser,
+                                  password: db_config.key,
+                                  socket: db_config.respond_to?(:socket) ? db_config.socket : nil,
+                                  port: db_config.respond_to?(:port) ? db_config.port : nil,
+                                  flags: 'SESSION_TRACK',
+                                  init_command: 'SET @@SESSION.session_track_schema=ON'
+                                )
+      rescue StandardError => e
+        @my = nil
+        raise e
+      end
+      raise Mysql2::Error, 2002 if @my.nil?
+
+      # @@my.reconnect = true
+      if block_given?
+        yield
+        return close
+      end
+      return @my
+    end
+
+    alias open connect
+
+    # close the mySQL connection. Call only if connect was not given a block.
+    #
+    # @return [NilClass]
+    def close
+      @my.close if @my != nil
+      return (@my = nil)
+    end
+
+    # Call underlying connector's escape of the query string
+    # @param query [String] The SQL query
+    # @return [String] The SQL query, escaped to remove vulnerabilities
+    def self.escape(query)
+      Mysql2::Client.escape(query)
+    end
+
+    # Call underlying connector's escape of the query string
+    # @param query [String] The SQL query
+    # @return [String] The SQL query, escaped to remove vulnerabilities
+    def escape(query)
+      @my.escape(query)
+    end
+
+    # Run a query on the DB server.
+    #
+    # @param the_query [String]  Sql query to send to DB server.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [Mysql::Result] @result and @affected_rows are also set.
+    # @return [Mysql::Result] @result and @affected_rows are also set.
+    def query(the_query, options = nil )
+      raise Mysql2::Error, 2002 if @my.nil?
+
+      # Default to returning values as an array, with no caching of previous results
+      # This is consistent with ruby-mysql
+      options ||= { as: :array, cache_rows: false }
+      begin
+        if @result != nil
+          @result.free # Free any result we had left over from previous use.
+          @result = nil
+        end
+        @affected_rows = 0 # incase this query crashes and burns, this will have a value.
+        @result = @my.query(the_query, options)
+        @affected_rows = @my.affected_rows # This is non-zero for select/insert/delete/update of rows
+        if block_given?
+          yield @result
+        else
+          return @result
+        end
+      rescue Mysql2::Error => e
+        if @result != nil
+          @result.free # Free any result we had left over from previous use.
+          @result = nil
+        end
+        raise e
+      end
+    end
+
+    # Perform a transaction in the passed block.
+    # RollBACK on error, otherwise COMMIT
+    #
+    # @yieldparam [] yields to block, where the queries are performed.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    def transaction
+      raise Mysql2::Error, 2002 if @my.nil?
+
+      if block_given?
+        begin
+          @my.query('START TRANSACTION WITH CONSISTENT SNAPSHOT')
+          yield # Start executing the query black.
+          @my.query('COMMIT')
+        rescue Mysql2::Error => e
+          @my.query('ROLLBACK')
+          raise e
+        end
+      end
+    end
+
+    # Yields query query results row by row, as Array
+    #
+    # @param the_query [String]  Sql query to send to DB server.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [Array] each result row
+    # @return [Array] of rows
+    # @note @result and @affected_rows are also set via call to query().
+    def each_row(the_query, &block)
+      begin
+        query(the_query, { as: :array, cache_rows: false })
+        unless @result.nil?
+          if block_given?
+            @affected_rows = @result.count # This is non-zero is we do a select, and get results.
+            @result.each(&block)
+          else
+            result = []
+            @result.each { |row| result << row }
+            return result
+          end
+        end
+      rescue Mysql2::Error => e
+        # puts "#{e.errno}: #{e.error}"
+        raise e
+      ensure
+        if block_given? && @result != nil
+          @result.free
+        end
+      end
+    end
+
+    alias query_array each_row
+
+    # Yields query result row by row, as Hash, using String keys
+    #
+    # @param the_query [String]  Sql query to send to DB server.
+    # @param with_table_names [Boolean] if TrueClass, then table names are included in the hash keys.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [Hash] each result row
+    # @return [Array] If no block is given:  of rows with hash keys
+    # @note @result and @affected_rows are also set via call to query().
+    def each_hash(the_query, with_table_names = false, &block)
+      begin
+        if with_table_names
+          # We have to build the hash ourselves, if we want table names included
+          query(the_query, { as: :array, cache_rows: false })
+          if @result != nil
+            fields = @result.fields
+            tables = @result.respond_to?(:tables) ? @result.tables : [] # My addition to mysql2 results.c
+
+            result = []
+            @result.each do |row|
+              hrow = {}
+              (0...row.length).each do |i|
+                field_name = tables[i].nil? ? fields[i] : "#{tables[i]}.#{fields[i]}"
+                hrow[field_name] = row[i]
+              end
+              yield hrow
+              result << hrow
+            end
+            return result
+          end
+        else
+          query(the_query, { as: :hash, cache_rows: false })
+          if @result != nil
+            if block_given?
+              @result.each(&block)
+            else
+              return @result.to_a
+            end
+          end
+        end
+      rescue Mysql2::Error => e
+        # puts "#{e.errno}: #{e.error}"
+        raise e
+      ensure
+        if block_given? && @result != nil
+          @result.free
+        end
+      end
+    end
+
+    alias query_hash each_hash
+
+    # Yields query result row by row, as Hash using Symbol keys, so can't have table names included.
+    # This can be used with keyword arguments. eg. each_sym { |key1:, key2:, ..., **rest_of_args| do something }
+    #
+    # @param the_query [String]  Sql query to send to DB server.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [Hash] each result row
+    # @return [Array] If no block is given: of hashed rows with symbol keys.
+    # @note @result and @affected_rows are also set via call to query().
+    def each_sym(the_query, &block)
+      query(the_query, { symbolize_keys: true, as: :hash, cache_rows: false })
+      if @result != nil
+        if block_given?
+          @result.each(&block)
+        else
+          return @result.to_a
+        end
+      end
+    end
+
+    alias query_sym each_sym
+
+    # Yields query result row by row, as **Hash using Symbol keys, so can't have table names included.
+    # This can be used with keyword arguments. eg. each_sym { |key1:, key2:, ..., **rest_of_args| do something }
+    #
+    # @param the_query [String]  Sql query to send to DB server.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [**Hash] each result row
+    # @return [Array] If no block is given: of hashed rows with symbol keys.
+    # @note @result and @affected_rows are also set via call to query().
+    def each_param(the_query)
+      query(the_query, { symbolize_keys: true, as: :hash, cache_rows: false })
+      if @result != nil
+        if block_given?
+          @result.each { |row| yield(**row) }
+        else
+          return @result.to_a
+        end
+      end
+    end
+
+    # Get the database field attributes from a query result.
+    #
+    # @return [Array][Mysql::Field] Array of field records
+    # @note mySQL2 doesn't expose this structure. Only parts of it.
+    def fetch_fields
+      fields = @result.fields
+      field_types = @result.field_types
+      tables = @result.respond_to?(:tables) ? @result.tables : [] # My addition to mysql2 results.c
+      fields_arr = []
+      (0...@result.fields.length).each do |i|
+        fields_arr[i] = MySQL_FIELD.new(
+          name: fields[i],
+          table: tables[i],
+          db: databases[i],
+          type: field_types[i]
+        )
+      end
+      return fields_arr
+    end
+
+    # Create WIKK::SQL instance and set up the mySQL connection, and Run a query on the DB server.
+    #
+    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
+    # @param the_query [String]  Sql query to send to DB server.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [Mysql::Result] @result and @affected_rows are also set.
+    # @return [Mysql::Result] @result and @affected_rows are also set.
+    def self.query(db_config, the_query)
+      self.connect db_config do |sql|
+        result = sql.query(the_query)
+        if block_given?
+          yield result
+          return sql.affected_rows
+        else
+          return result
+        end
+      end
+    end
+
+    # Create WIKK::SQL instance and set up the mySQL connection, and Run a query on the DB server.
+    # Yields query query results row by row, as Array
+    #
+    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
+    # @param the_query [String]  Sql query to send to DB server.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [Array] each result row
+    # @note @result and @affected_rows are also set via call to query().
+    def self.each_row(db_config, query, &block)
+      self.connect db_config do |sql|
+        if block_given?
+          sql.each_row(query, &block)
+          return sql.affected_rows
+        else
+          return sql.each_row(query)
+        end
+      end
+    end
+
+    # Create WIKK::SQL instance and set up the mySQL connection, and Run a query on the DB server.
+    # Yields query result row by row, as Hash, using String keys
+    #
+    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
+    # @param the_query [String]  Sql query to send to DB server.
+    # @param with_table_names [Boolean] if TrueClass, then table names are included in the hash keys.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [Hash] each result row
+    # @note @result and @affected_rows are also set via call to query().
+    def self.each_hash(db_config, query, with_table_names = false, &block)
+      self.connect( db_config ) do |sql|
+        if block_given?
+          sql.each_hash(query, with_table_names, &block)
+          return sql.affected_rows
+        else
+          return sql.each_hash(query, with_table_names)
+        end
+      end
+    end
+
+    # Create WIKK::SQL instance and set up the mySQL connection, and Run a query on the DB server.
+    # Yields query result row by row, as Hash using Symbol keys, so can't have table names included.
+    #
+    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
+    # This can be used with keyword arguments. eg. each_sym { |key1:, key2:, ..., **rest_of_args| do something }
+    # @param the_query [String]  Sql query to send to DB server.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [Hash] each result row
+    # @note @result and @affected_rows are also set via call to query().
+    def self.each_sym(db_config, query, &block)
+      self.connect( db_config ) do |sql|
+        if block_given?
+          sql.each_sym(query, &block)
+          return sql  # May be useful to access the affected rows
+        else
+          return sql.each_sym(query)
+        end
+      end
+    end
+
+    # Create WIKK::SQL instance and set up the mySQL connection, and Run a query on the DB server.
+    # Yields query result row by row, as Hash using Symbol keys, so can't have table names included.
+    #
+    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
+    # This can be used with keyword arguments. eg. each_sym { |key1:, key2:, ..., **rest_of_args| do something }
+    # @param the_query [String]  Sql query to send to DB server.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [**Hash] for each result row, which can be passed to named args in a block
+    # @note @result and @affected_rows are also set via call to query().
+    def self.each_param(db_config, query, &block)
+      self.connect( db_config ) do |sql|
+        if block_given?
+          sql.each_param(query, &block)
+          return sql  # May be useful to access the affected rows
+        else
+          return sql.each_sym(query)
+        end
+      end
+    end
+  end
+end

data/lib/wikk_ruby_mysql.rb

@@ -0,0 +1,341 @@
+require 'mysql'
+
+# Provides common front end, even if we change the connector library
+# Connector is ruby-mysql native ruby gem
+module WIKK
+  # WIKK_SQL wrapper for ruby mysql gem.
+  # @attr_reader [Numeric] affected_rows the number of rows changed, deleted, or added.
+  # @attr_reader [Mysql::Result] result the last query's result
+  # @attr_reader [Mysql] my the DB connection descriptor
+  class SQL
+    attr_reader :affected_rows, :result, :my
+
+    # Create WIKK::SQL instance and set up the mySQL connection.
+    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
+    # @yieldparam sql [WIKK_SQL] if a block is given.
+    # @return [NilClass] if block is given, and closes the mySQL connection.
+    # @return [WIKK_SQL] if no block is given, and caller must call sql.close
+    def self.connect(db_config)
+      sql = self.new          # Create an instance of WIKK::SQL
+      sql.connect(db_config)  # Connect to the database
+      if block_given?
+        yield sql             # Yield the instance, so caller can access methods
+        return sql.close      # Clean up at end of the callers block
+      else
+        return sql            # Return new instance of WIKK::SQL
+      end
+    end
+
+    # Set up the mySQL connection.
+    #
+    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
+    # @yieldparam [] if a block is given.
+    # @return [NilClass] if block is given, and closes the mySQL connection.
+    # @return [WIKK_SQL] if no block is given, and caller must call sql.close
+    def connect(db_config)
+      if db_config.instance_of?(Hash)
+        sym = db_config.transform_keys(& :to_sym )
+        db_config = Struct.new(*(k = sym.keys)).new(*sym.values_at(*k))
+      end
+
+      begin
+        @my = Mysql.new(db_config.host, db_config.dbuser, db_config.key, db_config.db )
+      rescue StandardError => e
+        @my = nil
+        raise e
+      end
+      raise Mysql::Error, 'Not Connected' if @my.nil?
+
+      # @@my.reconnect = true
+      if block_given?
+        yield
+        return close
+      end
+      return @my
+    end
+
+    alias open connect
+
+    # close the mySQL connection. Call only if connect was not given a block.
+    #
+    # @return [NilClass]
+    def close
+      @my.close if @my != nil
+      return (@my = nil)
+    end
+
+    # Call underlying connector's escape of the query string
+    # @param query [String] The SQL query
+    # @return [String] The SQL query, escaped to remove vulnerabilities
+    def self.escape(query)
+      Mysql.escape_string(query)
+    end
+
+    # Call underlying connector's escape of the query string
+    # @param query [String] The SQL query
+    # @return [String] The SQL query, escaped to remove vulnerabilities
+    def self.escape(query)
+      Mysql.escape_string(query)
+    end
+
+    # Run a query on the DB server.
+    #
+    # @param the_query [String]  Sql query to send to DB server.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [Mysql::Result] @result and @affected_rows are also set.
+    # @return [Mysql::Result] @result and @affected_rows are also set.
+    def query(the_query)
+      raise Mysql::Error, 'Not Connected' if @my.nil?
+
+      begin
+        if @result != nil
+          @result.free # Free any result we had left over from previous use.
+          @result = nil
+        end
+        @affected_rows = 0 # incase this query crashes and burns, this will have a value.
+        @result = @my.query(the_query)
+        @affected_rows = @my.affected_rows # This is non-zero for insert/delete/update of rows
+        if block_given?
+          yield @result
+        else
+          return @result
+        end
+      rescue Mysql::Error => e
+        if @result != nil
+          @result.free # Free any result we had left over from previous use.
+          @result = nil
+        end
+        raise e
+      end
+    end
+
+    # Perform a transaction in the passed block.
+    # RollBACK on error, otherwise COMMIT
+    #
+    # @yieldparam [] yields to block, where the queries are performed.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    def transaction
+      raise Mysql::Error, 'Not Connected' if @my.nil?
+
+      if block_given?
+        begin
+          @my.query('START TRANSACTION WITH CONSISTENT SNAPSHOT')
+          yield # Start executing the query black.
+          @my.query('COMMIT')
+        rescue Mysql::Error => e
+          @my.query('ROLLBACK')
+          raise e
+        end
+      end
+    end
+
+    # Yields query query results row by row, as Array
+    #
+    # @param the_query [String]  Sql query to send to DB server.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [Array] each result row
+    # @return [Array] Array of rows
+    # @note @result and @affected_rows are also set via call to query().
+    def each_row(the_query, &block)
+      begin
+        query(the_query)
+        unless @result.nil?
+          @affected_rows = @result.num_rows # This is non-zero is we do a select, and get results.
+          if block_given?
+            @result.each(&block)
+          else
+            result = []
+            @result.each { |row| result << row }
+            return result
+          end
+        end
+      rescue Mysql::Error => e
+        # puts "#{e.errno}: #{e.error}"
+        raise e
+      ensure
+        if block_given? && @result != nil
+          @result.free
+        end
+      end
+    end
+
+    alias query_array each_row
+
+    # Yields query result row by row, as Hash, using String keys
+    #
+    # @param the_query [String]  Sql query to send to DB server.
+    # @param with_table_names [Boolean] if TrueClass, then table names are included in the hash keys.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [Hash] each result row
+    # @return [Array] all rows, if no block is given
+    # @note @result and @affected_rows are also set via call to query().
+    def each_hash(the_query, with_table_names = false, &block)
+      begin
+        query(the_query)
+        unless @result.nil?
+          @affected_rows = @result.num_rows # This is non-zero is we do a select, and get results.
+          if block_given?
+            @result.each_hash(with_table_names, &block)
+          else
+            result = []
+            @result.each_hash(with_table_names) { |row| result << row }
+            return result
+          end
+        end
+      rescue Mysql::Error => e
+        # puts "#{e.errno}: #{e.error}"
+        raise e
+      ensure
+        if block_given? && @result != nil
+          @result.free
+        end
+      end
+    end
+
+    alias query_hash each_hash
+
+    # Yields query result row by row, as Hash using Symbol keys, so can't have table names included.
+    # This can be used with keyword arguments. eg. each_sym { |key1:, key2:, ..., **rest_of_args| do something }
+    #
+    # @param the_query [String]  Sql query to send to DB server.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [Hash] each result row
+    # @return [Array] if no block is given, returns an Array of Hash'd rows, with symbol as the key
+    # @note @result and @affected_rows are also set via call to query().
+    def each_sym(the_query)
+      if block_given?
+        each_hash(the_query) { |row| yield row.transform_keys(& :to_sym ) }
+      else
+        result = []
+        each_hash(the_query) { |row| result << row.transform_keys(& :to_sym ) }
+        return result
+      end
+    end
+
+    alias query_sym each_sym
+
+    # Yields query result row by row, as **Hash using Symbol keys, so can't have table names included.
+    # This can be used with keyword arguments. eg. each_sym { |key1:, key2:, ..., **rest_of_args| do something }
+    #
+    # @param the_query [String]  Sql query to send to DB server.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [**Hash] each result row
+    # @return [Array] if no block is given, returns an Array of Hash'd rows, with symbol as the key
+    # @note @result and @affected_rows are also set via call to query().
+    def each_param(the_query)
+      if block_given?
+        each_hash(the_query) { |row| yield(**row.transform_keys(& :to_sym )) }
+      else
+        result = []
+        each_hash(the_query) { |row| result << row.transform_keys(& :to_sym ) }
+        return result
+      end
+    end
+
+    # Get the database field attributes from a query result.
+    #
+    # @return [Array][Mysql::Field] Array of field records
+    # @note fields are name (of field), table (name), def, type, length, max_length, flags,decimals
+    def fetch_fields
+      @result.fetch_fields
+    end
+
+    # Create WIKK::SQL instance and set up the mySQL connection, and Run a query on the DB server.
+    #
+    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
+    # @param the_query [String]  Sql query to send to DB server.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [Mysql::Result] @result and @affected_rows are also set.
+    # @return [Mysql::Result] @result and @affected_rows are also set.
+    def self.query(db_config, the_query)
+      self.connect db_config do |sql|
+        result = sql.query(the_query)
+        if block_given?
+          yield result
+          return sql.affected_rows
+        else
+          return result
+        end
+      end
+    end
+
+    # Create WIKK::SQL instance and set up the mySQL connection, and Run a query on the DB server.
+    # Yields query query results row by row, as Array
+    #
+    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
+    # @param the_query [String]  Sql query to send to DB server.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [Array] each result row
+    # @note @result and @affected_rows are also set via call to query().
+    def self.each_row(db_config, query, &block)
+      self.connect db_config do |sql|
+        if block_given?
+          sql.each_row(query, &block)
+          return sql.affected_rows
+        else
+          return sql.each_row(query)
+        end
+      end
+    end
+
+    # Create WIKK::SQL instance and set up the mySQL connection, and Run a query on the DB server.
+    # Yields query result row by row, as Hash, using String keys
+    #
+    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
+    # @param the_query [String]  Sql query to send to DB server.
+    # @param with_table_names [Boolean] if TrueClass, then table names are included in the hash keys.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [Hash] each result row
+    # @note @result and @affected_rows are also set via call to query().
+    def self.each_hash(db_config, query, with_table_names = false, &block)
+      self.connect( db_config ) do |sql|
+        if block_given?
+          sql.each_hash(query, with_table_names, &block)
+          return sql.affected_rows
+        else
+          return sql.each_hash(query, with_table_names)
+        end
+      end
+    end
+
+    # Create WIKK::SQL instance and set up the mySQL connection, and Run a query on the DB server.
+    # Yields query result row by row, as Hash using Symbol keys, so can't have table names included.
+    #
+    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
+    # This can be used with keyword arguments. eg. each_sym { |key1:, key2:, ..., **rest_of_args| do something }
+    # @param the_query [String]  Sql query to send to DB server.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [Hash] each result row
+    # @note @result and @affected_rows are also set via call to query().
+    def self.each_sym(db_config, query, &block)
+      self.connect( db_config ) do |sql|
+        if block_given?
+          sql.each_sym(query, &block)
+          return sql  # May be useful to access the affected rows
+        else
+          return sql.each_sym(query)
+        end
+      end
+    end
+
+    # Create WIKK::SQL instance and set up the mySQL connection, and Run a query on the DB server.
+    # Yields query result row by row, as Hash using Symbol keys, so can't have table names included.
+    #
+    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
+    # This can be used with keyword arguments. eg. each_sym { |key1:, key2:, ..., **rest_of_args| do something }
+    # @param the_query [String]  Sql query to send to DB server.
+    # @raise [Mysql] passes on Mysql errors, freeing the result.
+    # @yieldparam [**Hash] for each result row, which can be passed to named args in a block
+    # @note @result and @affected_rows are also set via call to query().
+    def self.each_param(db_config, query, &block)
+      self.connect( db_config ) do |sql|
+        if block_given?
+          sql.each_param(query, &block)
+          return sql  # May be useful to access the affected rows
+        else
+          return sql.each_sym(query)
+        end
+      end
+    end
+  end
+end

data/lib/wikk_sql.rb

@@ -1,262 +1,44 @@
+# Provides common front end, even if we change the connector library
+# Choice of ruby-mysql or mysql2 connectors
 module WIKK
-  require 'mysql'
   require 'pp'
   require 'json'
 
-  #WIKK_SQL wrapper for ruby mysql gem.
-  # @attr_reader [Numeric] affected_rows the number of rows changed, deleted, or added.
-  # @attr_reader [Mysql::Result] result the last query's result
-  # @attr_reader [Mysql] my the DB connection descriptor
-  class SQL
-    VERSION = '0.1.2'
-
-    attr_reader :affected_rows, :result, :my
-    
-    #Create WIKK::SQL instance and set up the mySQL connection.
-    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
-    # @yieldparam sql [WIKK_SQL] if a block is given.
-    # @return [NilClass] if block is given, and closes the mySQL connection. 
-    # @return [WIKK_SQL] if no block is given, and caller must call sql.close 
-    def self.connect(db_config)
-      sql = self.new
-      sql.connect(db_config)
-      if block_given?
-        yield sql
-        return sql.close
-      else
-        return sql
-      end
-    end
-  
-    #Set up the mySQL connection.
-    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
-    # @yieldparam [] if a block is given.
-    # @return [NilClass] if block is given, and closes the mySQL connection. 
-    # @return [WIKK_SQL] if no block is given, and caller must call sql.close 
-    def connect(db_config)
-      if db_config.class == Hash
-        sym = db_config.each_with_object({}) { |(k,v),h| h[k.to_sym] = v }
-        db_config = Struct.new(*(k = sym.keys)).new(*sym.values_at(*k))
-      end
-    
-      @my = Mysql::new(db_config.host, db_config.dbuser, db_config.key, db_config.db ) 
-      #@@my.reconnect = true
-      if block_given?
-        yield
-        return close
-      end
-      return @my
-    end
-  
-    alias open connect
-  
-    #close the mySQL connection. Call only if connect was not given a block.
-    # @return [NilClass]
-    def close
-      @my.close if @my != nil
-      return (@my = nil)
-    end
-  
-    #Run a query on the DB server.
-    # @param the_query [String]  Sql query to send to DB server.
-    # @raise [Mysql] passes on Mysql errors, freeing the result.
-    # @yieldparam [Mysql::Result] @result and @affected_rows are also set.
-    # @return [Mysql::Result] @result and @affected_rows are also set.
-    def query(the_query)
-      begin
-        if result != nil 
-          @result.free #Free any result we had left over from previous use.
-          @result = nil
-        end
-        @affected_rows = 0 #incase this query crashes and burns, this will have a value.
-        @result = @my.query(the_query)
-        @affected_rows = @my.affected_rows #This is non-zero for insert/delete/update of rows
-        if block_given?
-          yield @result
-        else
-          return @result
-        end
-      rescue Mysql::Error => e
-        if result != nil 
-          @result.free #Free any result we had left over from previous use.
-          @result = nil
-        end
-        raise e
-      end
-    end
-
-    #Perform a transaction in the passed block.
-    #RollBACK on error, otherwise COMMIT
-    # @yieldparam [] yields to block, where the queries are performed.
-    # @raise [Mysql] passes on Mysql errors, freeing the result.
-    def transaction
-      puts "transaction"
-      if block_given?
-        begin
-          @my.query("START TRANSACTION WITH CONSISTENT SNAPSHOT")
-          yield #Start executing the query black.
-          @my.query("COMMIT")
-        rescue Mysql::Error => e
-          @my.query("ROLLBACK")
-          raise e
-        end
-      end
-    end
-    
-    #Yields query query results row by row, as Array
-    # @param the_query [String]  Sql query to send to DB server.
-    # @raise [Mysql] passes on Mysql errors, freeing the result.
-    # @yieldparam [Array] each result row
-    # @note @result and @affected_rows are also set via call to query().
-    def each_row(the_query)
-      begin
-        query(the_query)
-        if @result != nil && block_given?
-          @affected_rows = @result.num_rows() #This is non-zero is we do a select, and get results.
-          @result.each do |row|
-            yield row #return one row at a time to the block
-          end
-        end
-      rescue Mysql::Error => e
-        #puts "#{e.errno}: #{e.error}"
-        raise e
-      ensure
-        if block_given? && @result != nil
-          @result.free
-        end
-      end
-    end 
-  
-    #Yields query result row by row, as Hash, using String keys
-    # @param the_query [String]  Sql query to send to DB server.
-    # @param with_table_names [Boolean] if TrueClass, then table names are included in the hash keys.
-    # @raise [Mysql] passes on Mysql errors, freeing the result.
-    # @yieldparam [Hash] each result row
-    # @note @result and @affected_rows are also set via call to query().
-    def each_hash(the_query, with_table_names=false)
-      begin
-        query(the_query)
-        if @result != nil && block_given?
-          @affected_rows = @result.num_rows() #This is non-zero is we do a select, and get results.
-          @result.each_hash(with_table_names) do |row|
-            yield row
-          end
-        end
-      rescue Mysql::Error => e
-        #puts "#{e.errno}: #{e.error}"
-        raise e
-      ensure
-        if block_given? && @result != nil
-          @result.free
-        end
-      end
-    end 
-  
-    #Yields query result row by row, as Hash using Symbol keys, so can't have table names included.
-    #This can be used with keyword arguments. eg. each_sym { |key1:, key2:, ..., **rest_of_args| do something }
-    # @param the_query [String]  Sql query to send to DB server.
-    # @raise [Mysql] passes on Mysql errors, freeing the result.
-    # @yieldparam [Hash] each result row
-    # @note @result and @affected_rows are also set via call to query().
-    def each_sym(the_query)
-      each_hash(the_query) do |row_hash|
-        yield row_hash.each_with_object({}) { |(k,v),h| h[k.to_sym] = v }
-      end
-    end
-
-    #Get the database field attributes from a query result.
-    # @yieldparam [Array][Mysql::Field] Array of field records
-    # @note fields are name (of field), table (name), def, type, length, max_length, flags,decimals
-    def fetch_fields
-      @result.fetch_fields
-    end
-
-    #Create WIKK::SQL instance and set up the mySQL connection, and Run a query on the DB server.
-    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
-    # @param the_query [String]  Sql query to send to DB server.
-    # @raise [Mysql] passes on Mysql errors, freeing the result.
-    # @yieldparam [Mysql::Result] @result and @affected_rows are also set.
-    # @return [Mysql::Result] @result and @affected_rows are also set.
-    def self.query(db_config, the_query)
-      sql = self.new
-      sql.open db_config
-      begin
-        result = sql.query(the_query)
-        if block_given?
-          yield result
-        end
-      ensure
-        sql.close
-      end
-      return result
-    end
+  # From mysql.h, but mostly blank for both our connectors
+  MySQL_FIELD = Struct.new(
+    :name,        # Field name. Could be an 'as' alias
+    :org_name,    # Field name, not aliased (for introspection)
+    :table,       # Table name. Could be an 'as' alias
+    :org_table,   # Table name, not aliased (for introspection)
+    :db,          # database for table (useful for multitable queries)
+    :catalog,     # catalog for table
+    :def,         # Default value (if code wants to revert to the default)
+    :col_width,   # Width of column (length in mysql.h, but length is taken in Ruby)
+    :max_length,  # Max width for selected set
+    :flags,       # Div flags
+    :decimals,    # Number of decimals in field
+    :charsetnr,   # Character set
+    :type,        # Field type
+    :extension
+  )
 
-    #Create WIKK::SQL instance and set up the mySQL connection, and Run a query on the DB server.
-    #Yields query query results row by row, as Array
-    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
-    # @param the_query [String]  Sql query to send to DB server.
-    # @raise [Mysql] passes on Mysql errors, freeing the result.
-    # @yieldparam [Array] each result row
-    # @note @result and @affected_rows are also set via call to query().
-    def self.each_row(db_config, query)
-      sql = self.new
-      sql.open db_config
-      begin
-        if block_given?
-          sql.each_row(query) { |y| yield y }
-        end
-      ensure
-        sql.close
-      end
-      return sql
-    end
-  
-    #Create WIKK::SQL instance and set up the mySQL connection, and Run a query on the DB server.
-    #Yields query result row by row, as Hash, using String keys
-    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
-    # @param the_query [String]  Sql query to send to DB server.
-    # @param with_table_names [Boolean] if TrueClass, then table names are included in the hash keys.
-    # @raise [Mysql] passes on Mysql errors, freeing the result.
-    # @yieldparam [Hash] each result row
-    # @note @result and @affected_rows are also set via call to query().
-    def self.each_hash(db_config, query, with_table_names=false)
-      sql = self.new
-      sql.open db_config
-      begin
-        if block_given?
-          sql.each_hash(query, with_table_names) do |res|
-            yield res
-          end
-        end
-      ensure
-        sql.close
-      end
-      return sql
-    end
+  class SQL
+    VERSION = '0.2.1'
+  end
 
-    #Create WIKK::SQL instance and set up the mySQL connection, and Run a query on the DB server.
-    #Yields query result row by row, as Hash using Symbol keys, so can't have table names included.
-    # @param db_config [Configuration]  Configuration class, Hash, or any class with appropriate attr_readers.
-    #This can be used with keyword arguments. eg. each_sym { |key1:, key2:, ..., **rest_of_args| do something }
-    # @param the_query [String]  Sql query to send to DB server.
-    # @raise [Mysql] passes on Mysql errors, freeing the result.
-    # @yieldparam [Hash] each result row
-    # @note @result and @affected_rows are also set via call to query().
-    def self.each_sym(db_config, query)
-      sql = self.new
-      sql.open db_config
-      begin
-        if block_given?
-          sql.each_sym(query) do |**res|
-            yield **res
-          end
-        end
-      ensure
-        sql.close
-      end
-      return sql
-    end
+  # Prefer mysql2 over ruby-mysql, as it is faster
+  # Downside is, mysql2 doesn't expose field table names.
+  begin
+    Gem::Specification.find_by_name('mysql2')
+  rescue Gem::MissingSpecError
+    begin
+      Gem::Specification.find_by_name('ruby-mysql')
+    rescue Gem::MissingSpecError
+      raise Gem::MissingSpecError 'Need either mysql2 or ruby-mysql gems'
+    else
+      require_relative 'wikk_ruby_mysql.rb'
+    end
+  else
+    require_relative 'wikk_mysql2.rb'
   end
 end
-
-

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wikk_sql
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.1
 platform: ruby
 authors:
 - Rob Burrowes
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2017-01-04 00:00:00.000000000 Z
+date: 2022-06-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hoe-yard
@@ -16,29 +16,31 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.2
+        version: 0.1.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.2
+        version: 0.1.3
 - !ruby/object:Gem::Dependency
   name: hoe
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.15'
+        version: '3.23'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.15'
-description: "```"
+        version: '3.23'
+description: |-
+  Wrappers around mysql gem.
+  Consolidation of bits of code from many of my projects, going back 10+ years, into a gem.
 email:
 - r.burrowes@auckland.ac.nz
 executables: []
@@ -52,12 +54,14 @@ files:
 - Manifest.txt
 - README.md
 - Rakefile
+- lib/wikk_mysql2.rb
+- lib/wikk_ruby_mysql.rb
 - lib/wikk_sql.rb
-homepage: http://rbur004.github.com/wikk_sql/
+homepage: https://wikarekare.github.io/wikk_sql/
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options:
 - "--markup"
 - markdown
@@ -78,9 +82,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.8
-signing_key: 
+rubygems_version: 3.2.22
+signing_key:
 specification_version: 4
-summary: "```"
+summary: Wrappers around mysql gem
 test_files: []