wikk_sql 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a744a86c6e09edf76e687152ed1cfd7a142abf24
+  data.tar.gz: 8d28c677617a9ca95dc050c388e229246178ec08
+SHA512:
+  metadata.gz: c1e9ac49a33767e2a8275c2c0c7b234ac555662e16c19462576ac333f78502e0aaa66b5f0221cb9c221218556aaf647986f780b1a13853c94a7e2db23c3a30c4
+  data.tar.gz: ccb74288baa0bbe90431f5376a64f16c75ab8de8a19259b0a15f96c42b7c2ca5e715fea771025910299febb0a4a9e90f391525d9d82ecd1a136b4c6e5c494235

data/History.txt

@@ -0,0 +1,10 @@
+robertburrowes	Sun Jun 19 14:01:08 2016 +1200
+	Encapsulation of SQL into module WIKK
+robertburrowes	Sun Jun 19 13:59:27 2016 +1200
+	Encapsulated in WIKK module. Allowed db_config to be Hash.
+robertburrowes	Sat Jun 18 21:16:41 2016 +1200
+	added args to class level examples
+robertburrowes	Sat Jun 18 21:13:02 2016 +1200
+	Format cleanup
+robertburrowes	Sat Jun 18 21:04:49 2016 +1200
+	First commit

data/Manifest.txt

@@ -0,0 +1,5 @@
+History.txt
+Manifest.txt
+README.md
+Rakefile
+lib/wikk_sql.rb

data/README.md

@@ -0,0 +1,104 @@
+# wikk_sql
+
+* http://rbur004.github.com/wikk_sql/
+* Source https://github.com/wikarekare/wikk_sql
+* Gem https://rubygems.org/gems/wikk_sql
+
+## DESCRIPTION:
+
+Wrappers around mysql gem.
+Consolidation of bits of code from many of my projects, going back 10+ years, into a gem.
+
+###Instance level
+```
+  connect(config)  { |sql| rest of block } #Aliased to open
+  close #Call if connect didn't get passed a block
+  query(the_query)
+  each_row(the_query) { |row| rest of block }  
+  each_hash(the_query, with_table_names) { |hash| rest of block }  
+  each_sym(the_query) { |sym:, sym:, ..., **hash| rest of block }
+  transaction { calls to query, each_row, each_hash or each_sym }
+  fetch_fields #Returns table field info
+  affected_rows #Returns the number of rows changed, inserted or deleted.
+```
+  
+###Class level calls mirror the instance level calls taking blocks
+```
+   WIKK::SQL::connect(config) { |sql| rest of block }  
+   WIKK::SQL::each_row(config,the_query) { |row| rest of block }  
+   WIKK::SQL::each_hash(config,the_query, with_table_names=false) { |hash| rest of block }  
+   WIKK::SQL::each_sym(config,the_query) { |sym:, sym:, ..., **hash| rest of block }
+```
+   
+###Config
+```
+Any class, such as the WIKK::Configuration class, with attr_readers
+    host    #String hostname or IP Address
+    db      #String database name
+    dbuser  #String user to connect to DB as.
+    key     #"password" for db user account.
+Or Hash
+    {"host" => "hostname", "db" => "database", "dbuser" => "username", "key" => "password"}
+```
+  
+## FEATURES/PROBLEMS:
+
+
+## SYNOPSIS:
+
+###Instance example
+```
+  WIKK::SQL::connect(@config) do |sql|
+    sql.each_hash("select * from customer limit 2", with_table_names = true) do |row|
+      row.each do |k,v|
+        printf "  %s => %s\n", k, v
+      end
+    end
+    puts "Number of rows returned: #{sql.affected_rows}"
+  end
+```
+  
+###Class level example
+```
+  WIKK::SQL::each_sym(@config, "select * from customer limit 2") do |customer_id:, name:, site_name:, **row|
+    printf "customer_id %s  site_name %s name %s\n", customer_id, site_name, name
+  end
+```
+  
+
+## REQUIREMENTS:
+
+* require 'wikk_sql'
+
+Can use wikk_configuration gem to load config from a json file.
+
+## INSTALL:
+
+* sudo gem install wikk_sql
+
+## LICENSE:
+
+(The MIT License)
+
+Encapsulates Wikarekare code used in library form, from 2004 to present day, as a gem.
+
+Copyright (c) 2004-2016
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +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")
+  remote_rdoc_dir = '' # Release to root
+  
+  self.yard_title = 'wikk_sql'
+  self.yard_options = ['--markup', 'markdown', '--protected']
+end
+
+
+#Validate manfest.txt
+#rake check_manifest
+
+#Local checking. Creates pkg/
+#rake gem
+
+#create doc/
+#rake docs  
+
+#Copy up to rubygem.org
+#rake release VERSION=1.0.1

data/lib/wikk_sql.rb

@@ -0,0 +1,262 @@
+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.1'
+
+    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.
+        @affected_rows = @my.affected_rows #This is non-zero for insert/delete/update of rows
+        @result = @my.query(the_query)
+        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
+
+    #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
+
+    #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
+  end
+end
+
+

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: wikk_sql
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Rob Burrowes
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-06-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hoe-yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+- !ruby/object:Gem::Dependency
+  name: hoe
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.15'
+description: "```"
+email:
+- r.burrowes@auckland.ac.nz
+executables: []
+extensions: []
+extra_rdoc_files:
+- History.txt
+- Manifest.txt
+- README.md
+files:
+- History.txt
+- Manifest.txt
+- README.md
+- Rakefile
+- lib/wikk_sql.rb
+homepage: http://rbur004.github.com/wikk_sql/
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--markup"
+- markdown
+- "--protected"
+- "--title"
+- wikk_sql
+- "--quiet"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: "```"
+test_files: []