ruby-mysql 3.0.1 → 4.1.0

data/lib/mysql.rb

@@ -1,4 +1,5 @@
 # coding: ascii-8bit
+
 # Copyright (C) 2008 TOMITA Masahiro
 # mailto:tommy@tmtm.org
 
@@ -12,15 +13,17 @@ require 'uri'
 #    p c1, c2
 #  end
 class Mysql
-
+  require_relative "mysql/field"
+  require_relative "mysql/result"
+  require_relative "mysql/stmt"
   require_relative "mysql/constants"
   require_relative "mysql/error"
   require_relative "mysql/charset"
   require_relative "mysql/protocol"
-  require_relative "mysql/packet.rb"
+  require_relative "mysql/packet"
 
-  VERSION            = '3.0.1'             # Version number of this library
-  MYSQL_UNIX_PORT    = "/tmp/mysql.sock"   # UNIX domain socket filename
+  VERSION            = -'4.1.0'             # Version number of this library
+  MYSQL_UNIX_PORT    = -"/tmp/mysql.sock"   # UNIX domain socket filename
   MYSQL_TCP_PORT     = 3306                # TCP socket port number
 
   # @!attribute [rw] host
@@ -37,6 +40,8 @@ class Mysql
   #   @return [String, nil] socket filename
   # @!attribute [rw] flags
   #   @return [Integer, nil]
+  # @!attribute [rw] io
+  #   @return [[BasicSocket, OpenSSL::SSL::SSLSocket], nil]
   # @!attribute [rw] connect_timeout
   #   @return [Numeric, nil]
   # @!attribute [rw] read_timeout
@@ -51,8 +56,22 @@ class Mysql
   #   @return [String, nil]
   # @!attribute [rw] ssl_mode
   #   @return [String, Integer] 1 or "disabled" / 2 or "preferred" / 3 or "required"
+  # @!attribute [rw] ssl_context_params
+  #   @return [Hash] See OpenSSL::SSL::Context#set_params
   # @!attribute [rw] get_server_public_key
   #   @return [Boolean]
+  # @!attribute [rw] connect_attrs
+  #   @return [Hash]
+  # @!attribute [rw] yield_null_result
+  #   @return [Boolean]
+  # @!attribute [rw] return_result
+  #   @return [Boolean]
+  # @!attribute [rw] with_table
+  #   @return [Boolean]
+  # @!attribute [rw] auto_store_result
+  #   @return [Boolean]
+  # @!attribute [rw] cast
+  #   @return [Boolean]
   DEFAULT_OPTS = {
     host: nil,
     username: nil,
@@ -61,6 +80,7 @@ class Mysql
     port: nil,
     socket: nil,
     flags: 0,
+    io: nil,
     charset: nil,
     connect_timeout: nil,
     read_timeout: nil,
@@ -69,12 +89,25 @@ class Mysql
     local_infile: nil,
     load_data_local_dir: nil,
     ssl_mode: SSL_MODE_PREFERRED,
+    ssl_context_params: {},
     get_server_public_key: false,
+    connect_attrs: {},
+    yield_null_result: true,
+    return_result: true,
+    with_table: false,
+    auto_store_result: true,
+    cast: true,
   }.freeze
 
   # @private
   attr_reader :protocol
 
+  # @return [Array<Mysql::Field>] fields of result set
+  attr_reader :fields
+
+  # @return [Mysql::Result]
+  attr_reader :result
+
   class << self
     # Make Mysql object and connect to mysqld.
     # parameter is same as arguments for {#initialize}.
@@ -87,7 +120,7 @@ class Mysql
     # @param [String] str
     # @return [String]
     def escape_string(str)
-      str.gsub(/[\0\n\r\\\'\"\x1a]/) do |s|
+      str.gsub(/[\0\n\r\\'"\x1a]/) do |s|
         case s
         when "\0" then "\\0"
         when "\n" then "\\n"
@@ -98,6 +131,10 @@ class Mysql
       end
     end
     alias quote escape_string
+
+    def default_options
+      @default_options ||= DEFAULT_OPTS.dup
+    end
   end
 
   # @overload initialize(uri, **opts)
@@ -135,15 +172,18 @@ class Mysql
   #   @option opts :local_infile [Boolean]
   #   @option opts :load_data_local_dir [String]
   #   @option opts :ssl_mode [Integer]
+  #   @option opts :ssl_context_params [Hash<Symbol, String>]
   #   @option opts :get_server_public_key [Boolean]
+  #   @option opts :connect_attrs [Hash]
+  #   @option opts :io [BasicSocket, OpenSSL::SSL::SSLSocket] Existing socket instance that will be used instead of creating a new socket
   def initialize(*args, **opts)
     @fields = nil
+    @result = nil
     @protocol = nil
     @sqlstate = "00000"
     @host_info = nil
     @last_error = nil
-    @result_exist = false
-    @opts = DEFAULT_OPTS.dup
+    @opts = Mysql.default_options.dup
     parse_args(args, opts)
   end
 
@@ -164,23 +204,23 @@ class Mysql
   end
 
   def parse_args(args, opts)
-    case args[0]
-    when URI
-      uri = args[0]
-    when /\Amysql:\/\//
-      uri = URI.parse(args[0])
-    when String
-      @opts[:host], user, passwd, dbname, port, socket, flags = *args
-      @opts[:username] = user if user
-      @opts[:password] = passwd if passwd
-      @opts[:database] = dbname if dbname
-      @opts[:port] = port if port
-      @opts[:socket] = socket if socket
-      @opts[:flags] = flags if flags
-    when Hash
-      # skip
-    when nil
-      # skip
+    unless args.empty?
+      case args[0]
+      when URI
+        uri = args[0]
+      when /\Amysql:\/\//
+        uri = URI.parse(args[0])
+      when String, nil
+        @opts[:host], user, passwd, dbname, port, socket, flags = *args
+        @opts[:username] = user if user
+        @opts[:password] = passwd if passwd
+        @opts[:database] = dbname if dbname
+        @opts[:port] = port if port
+        @opts[:socket] = socket if socket
+        @opts[:flags] = flags if flags
+      when Hash
+        # skip
+      end
     end
     if uri
       host = uri.hostname.to_s
@@ -252,7 +292,6 @@ class Mysql
       query "SET NAMES #{charset.name}"
     end
     @opts[:charset] = charset
-    cs
   end
 
   # @return [String] charset name
@@ -267,7 +306,7 @@ class Mysql
 
   # @return [String] last error message
   def error
-    @last_error && @last_error.error
+    @last_error&.error
   end
 
   # @return [String] sqlstate for last error
@@ -293,13 +332,12 @@ class Mysql
 
   # @return [Integer] server version
   def server_version
-    check_connection
-    @protocol.server_version
+    @protocol&.server_version
   end
 
   # @return [String] information for last query
   def info
-    @protocol && @protocol.message
+    @protocol&.message
   end
 
   # @return [Integer] number of affected records by insert/update/delete.
@@ -327,34 +365,33 @@ class Mysql
   end
 
   # Execute query string.
-  # @overload query(str)
-  #   @param [String] str Query.
-  #   @return [Mysql::Result]
-  #   @return [nil] if the query does not return result set.
-  # @overload query(str, &block)
-  #   @param [String] str Query.
-  #   @yield [Mysql::Result] evaluated per query.
-  #   @return [self]
+  # @param str [String] Query.
+  # @param return_result [Boolean]
+  # @param yield_null_result [Boolean]
+  # @return [Mysql::Result] if return_result is true and the query returns result set.
+  # @return [nil] if return_result is true and the query does not return result set.
+  # @return [self] if return_result is false or block is specified.
   # @example
   #  my.query("select 1,NULL,'abc'").fetch  # => [1, nil, "abc"]
   #  my.query("select 1,NULL,'abc'"){|res| res.fetch}
-  def query(str, &block)
+  def query(str, **opts, &block)
+    opts = @opts.merge(opts)
     check_connection
     @fields = nil
     begin
-      nfields = @protocol.query_command str
-      if nfields
-        @fields = @protocol.retr_fields nfields
-        @result_exist = true
-      end
+      @protocol.query_command str
       if block
         while true
-          block.call store_result if @fields
-          break unless next_result
+          @protocol.get_result
+          res = store_result(**opts)
+          block.call res if res || opts[:yield_null_result]
+          break unless more_results?
         end
         return self
       end
-      return @fields ? store_result : nil
+      @protocol.get_result
+      return self unless opts[:return_result]
+      return store_result(**opts)
     rescue ServerError => e
       @last_error = e
       @sqlstate = e.sqlstate
@@ -364,12 +401,12 @@ class Mysql
 
   # Get all data for last query.
   # @return [Mysql::Result]
-  def store_result
-    check_connection
-    raise ClientError, 'invalid usage' unless @result_exist
-    res = Result.new @fields, @protocol
-    @result_exist = false
-    res
+  # @return [nil] if no results
+  def store_result(**opts)
+    return nil if @protocol.field_count.nil? || @protocol.field_count == 0
+    @fields = @protocol.retr_fields
+    opts = @opts.merge(opts)
+    @result = Result.new(@fields, @protocol, **opts)
   end
 
   # @return [Integer] Thread ID
@@ -388,30 +425,29 @@ class Mysql
   end
 
   # @return [Boolean] true if multiple queries are specified and unexecuted queries exists.
-  def more_results
-    @protocol.server_status & SERVER_MORE_RESULTS_EXISTS != 0
+  def more_results?
+    @protocol.more_results?
   end
-  alias more_results? more_results
 
   # execute next query if multiple queries are specified.
-  # @return [Boolean] true if next query exists.
-  def next_result
-    return false unless more_results
-    check_connection
+  # @return [Mysql::Result] result set of query if return_result is true.
+  # @return [true] if return_result is false and result exists.
+  # @return [nil] query returns no results.
+  def next_result(**opts)
+    return nil unless more_results?
+    opts = @opts.merge(opts)
+    @protocol.get_result
     @fields = nil
-    nfields = @protocol.get_result
-    if nfields
-      @fields = @protocol.retr_fields nfields
-      @result_exist = true
-    end
-    return true
+    return store_result(**opts) if opts[:return_result]
+    true
   end
 
   # Parse prepared-statement.
   # @param [String] str query string
   # @return [Mysql::Stmt] Prepared-statement object
-  def prepare(str)
-    st = Stmt.new @protocol
+  def prepare(str, **opts)
+    opts = @opts.merge(opts)
+    st = Stmt.new(@protocol, **opts)
     st.prepare str
     st
   end
@@ -419,8 +455,9 @@ class Mysql
   # @private
   # Make empty prepared-statement object.
   # @return [Mysql::Stmt] If block is not specified.
-  def stmt
-    Stmt.new @protocol
+  def stmt(**opts)
+    opts = @opts.merge(opts)
+    Stmt.new(@protocol, **opts)
   end
 
   # Check whether the  connection is available.
@@ -488,462 +525,15 @@ class Mysql
     self
   end
 
-  private
-
-  def check_connection
-    raise ClientError::ServerGoneError, 'MySQL server has gone away' unless @protocol
-  end
-
-  # @!visibility public
-  # Field class
-  class Field
-    # @return [String] database name
-    attr_reader :db
-    # @return [String] table name
-    attr_reader :table
-    # @return [String] original table name
-    attr_reader :org_table
-    # @return [String] field name
-    attr_reader :name
-    # @return [String] original field name
-    attr_reader :org_name
-    # @return [Integer] charset id number
-    attr_reader :charsetnr
-    # @return [Integer] field length
-    attr_reader :length
-    # @return [Integer] field type
-    attr_reader :type
-    # @return [Integer] flag
-    attr_reader :flags
-    # @return [Integer] number of decimals
-    attr_reader :decimals
-    # @return [String] defualt value
-    attr_reader :default
-    alias :def :default
-
-    # @private
-    attr_accessor :result
-
-    # @attr [Protocol::FieldPacket] packet
-    def initialize(packet)
-      @db, @table, @org_table, @name, @org_name, @charsetnr, @length, @type, @flags, @decimals, @default =
-        packet.db, packet.table, packet.org_table, packet.name, packet.org_name, packet.charsetnr, packet.length, packet.type, packet.flags, packet.decimals, packet.default
-      @flags |= NUM_FLAG if is_num_type?
-      @max_length = nil
-    end
-
-    # @return [Hash] field information
-    def to_hash
-      {
-        "name"       => @name,
-        "table"      => @table,
-        "def"        => @default,
-        "type"       => @type,
-        "length"     => @length,
-        "max_length" => max_length,
-        "flags"      => @flags,
-        "decimals"   => @decimals
-      }
-    end
-
-    # @private
-    def inspect
-      "#<Mysql::Field:#{@name}>"
-    end
-
-    # @return [Boolean] true if numeric field.
-    def is_num?
-      @flags & NUM_FLAG != 0
-    end
-
-    # @return [Boolean] true if not null field.
-    def is_not_null?
-      @flags & NOT_NULL_FLAG != 0
-    end
-
-    # @return [Boolean] true if primary key field.
-    def is_pri_key?
-      @flags & PRI_KEY_FLAG != 0
-    end
-
-    # @return [Integer] maximum width of the field for the result set
-    def max_length
-      return @max_length if @max_length
-      @max_length = 0
-      @result.calculate_field_max_length if @result
-      @max_length
-    end
-
-    attr_writer :max_length
-
-    private
-
-    def is_num_type?
-      [TYPE_DECIMAL, TYPE_TINY, TYPE_SHORT, TYPE_LONG, TYPE_FLOAT, TYPE_DOUBLE, TYPE_LONGLONG, TYPE_INT24].include?(@type) || (@type == TYPE_TIMESTAMP && (@length == 14 || @length == 8))
-    end
-
-  end
-
-  # @!visibility public
-  # Result set
-  class ResultBase
-    include Enumerable
-
-    # @return [Array<Mysql::Field>] field list
-    attr_reader :fields
-
-    # @param [Array of Mysql::Field] fields
-    def initialize(fields)
-      @fields = fields
-      @field_index = 0             # index of field
-      @records = []                # all records
-      @index = 0                   # index of record
-      @fieldname_with_table = nil
-      @fetched_record = nil
-    end
-
-    # ignore
-    # @return [void]
-    def free
-    end
-
-    # @return [Integer] number of record
-    def size
-      @records.size
-    end
-    alias num_rows size
-
-    # @return [Array] current record data
-    def fetch
-      @fetched_record = nil
-      return nil if @index >= @records.size
-      @records[@index] = @records[@index].to_a unless @records[@index].is_a? Array
-      @fetched_record = @records[@index]
-      @index += 1
-      return @fetched_record
-    end
-    alias fetch_row fetch
-
-    # Return data of current record as Hash.
-    # The hash key is field name.
-    # @param [Boolean] with_table if true, hash key is "table_name.field_name".
-    # @return [Hash] current record data
-    def fetch_hash(with_table=nil)
-      row = fetch
-      return nil unless row
-      if with_table and @fieldname_with_table.nil?
-        @fieldname_with_table = @fields.map{|f| [f.table, f.name].join(".")}
-      end
-      ret = {}
-      @fields.each_index do |i|
-        fname = with_table ? @fieldname_with_table[i] : @fields[i].name
-        ret[fname] = row[i]
-      end
-      ret
-    end
-
-    # Iterate block with record.
-    # @yield [Array] record data
-    # @return [self] self. If block is not specified, this returns Enumerator.
-    def each(&block)
-      return enum_for(:each) unless block
-      while rec = fetch
-        block.call rec
-      end
-      self
-    end
-
-    # Iterate block with record as Hash.
-    # @param [Boolean] with_table if true, hash key is "table_name.field_name".
-    # @yield [Hash] record data
-    # @return [self] self. If block is not specified, this returns Enumerator.
-    def each_hash(with_table=nil, &block)
-      return enum_for(:each_hash, with_table) unless block
-      while rec = fetch_hash(with_table)
-        block.call rec
-      end
-      self
-    end
-
-    # Set record position
-    # @param [Integer] n record index
-    # @return [self] self
-    def data_seek(n)
-      @index = n
-      self
-    end
-
-    # @return [Integer] current record position
-    def row_tell
-      @index
-    end
-
-    # Set current position of record
-    # @param [Integer] n record index
-    # @return [Integer] previous position
-    def row_seek(n)
-      ret = @index
-      @index = n
-      ret
-    end
-  end
-
-  # @!visibility public
-  # Result set for simple query
-  class Result < ResultBase
-    # @private
-    # @param [Array<Mysql::Field>] fields
-    # @param [Mysql::Protocol] protocol
-    def initialize(fields, protocol=nil)
-      super fields
-      return unless protocol
-      @records = protocol.retr_all_records fields
-      fields.each{|f| f.result = self}  # for calculating max_field
-    end
-
-    # @private
-    # calculate max_length of all fields
-    def calculate_field_max_length
-      max_length = Array.new(@fields.size, 0)
-      @records.each_with_index do |rec, i|
-        rec = @records[i] = rec.to_a if rec.is_a? RawRecord
-        max_length.each_index do |j|
-          max_length[j] = rec[j].length if rec[j] && rec[j].length > max_length[j]
-        end
-      end
-      max_length.each_with_index do |len, i|
-        @fields[i].max_length = len
-      end
-    end
-
-    # @return [Mysql::Field] current field
-    def fetch_field
-      return nil if @field_index >= @fields.length
-      ret = @fields[@field_index]
-      @field_index += 1
-      ret
-    end
-
-    # @return [Integer] current field position
-    def field_tell
-      @field_index
-    end
-
-    # Set field position
-    # @param [Integer] n field index
-    # @return [Integer] previous position
-    def field_seek(n)
-      ret = @field_index
-      @field_index = n
-      ret
-    end
-
-    # Return specified field
-    # @param [Integer] n field index
-    # @return [Mysql::Field] field
-    def fetch_field_direct(n)
-      raise ClientError, "invalid argument: #{n}" if n < 0 or n >= @fields.length
-      @fields[n]
-    end
-
-    # @return [Array<Mysql::Field>] all fields
-    def fetch_fields
-      @fields
-    end
-
-    # @return [Array<Integer>] length of each fields
-    def fetch_lengths
-      return nil unless @fetched_record
-      @fetched_record.map{|c|c.nil? ? 0 : c.length}
-    end
-
-    # @return [Integer] number of fields
-    def num_fields
-      @fields.size
-    end
-  end
-
-  # @!visibility private
-  # Result set for prepared statement
-  class StatementResult < ResultBase
-    # @private
-    # @param [Array<Mysql::Field>] fields
-    # @param [Mysql::Protocol] protocol
-    def initialize(fields, protocol)
-      super fields
-      @records = protocol.stmt_retr_all_records @fields, protocol.charset
-    end
+  # session track
+  # @return [Hash]
+  def session_track
+    @protocol.session_track
   end
 
-  # @!visibility public
-  # Prepared statement
-  # @!attribute [r] affected_rows
-  #   @return [Integer]
-  # @!attribute [r] insert_id
-  #   @return [Integer]
-  # @!attribute [r] server_status
-  #   @return [Integer]
-  # @!attribute [r] warning_count
-  #   @return [Integer]
-  # @!attribute [r] param_count
-  #   @return [Integer]
-  # @!attribute [r] fields
-  #   @return [Array<Mysql::Field>]
-  # @!attribute [r] sqlstate
-  #   @return [String]
-  class Stmt
-    include Enumerable
-
-    attr_reader :affected_rows, :insert_id, :server_status, :warning_count
-    attr_reader :param_count, :fields, :sqlstate
-
-    # @private
-    def self.finalizer(protocol, statement_id)
-      proc do
-        protocol.gc_stmt statement_id
-      end
-    end
-
-    # @private
-    # @param [Mysql::Protocol] protocol
-    def initialize(protocol)
-      @protocol = protocol
-      @statement_id = nil
-      @affected_rows = @insert_id = @server_status = @warning_count = 0
-      @sqlstate = "00000"
-      @param_count = nil
-    end
-
-    # @private
-    # parse prepared-statement and return {Mysql::Stmt} object
-    # @param [String] str query string
-    # @return self
-    def prepare(str)
-      close
-      begin
-        @sqlstate = "00000"
-        @statement_id, @param_count, @fields = @protocol.stmt_prepare_command(str)
-      rescue ServerError => e
-        @last_error = e
-        @sqlstate = e.sqlstate
-        raise
-      end
-      ObjectSpace.define_finalizer(self, self.class.finalizer(@protocol, @statement_id))
-      self
-    end
-
-    # Execute prepared statement.
-    # @param [Object] values values passed to query
-    # @return [Mysql::Stmt] self
-    def execute(*values)
-      raise ClientError, "not prepared" unless @param_count
-      raise ClientError, "parameter count mismatch" if values.length != @param_count
-      values = values.map{|v| @protocol.charset.convert v}
-      begin
-        @sqlstate = "00000"
-        nfields = @protocol.stmt_execute_command @statement_id, values
-        if nfields
-          @fields = @protocol.retr_fields nfields
-          @result = StatementResult.new @fields, @protocol
-        else
-          @affected_rows, @insert_id, @server_status, @warning_count, @info =
-            @protocol.affected_rows, @protocol.insert_id, @protocol.server_status, @protocol.warning_count, @protocol.message
-        end
-        return self
-      rescue ServerError => e
-        @last_error = e
-        @sqlstate = e.sqlstate
-        raise
-      end
-    end
-
-    # Close prepared statement
-    # @return [void]
-    def close
-      ObjectSpace.undefine_finalizer(self)
-      @protocol.stmt_close_command @statement_id if @statement_id
-      @statement_id = nil
-    end
-
-    # @return [Array] current record data
-    def fetch
-      @result.fetch
-    end
-
-    # Return data of current record as Hash.
-    # The hash key is field name.
-    # @param [Boolean] with_table if true, hash key is "table_name.field_name".
-    # @return [Hash] record data
-    def fetch_hash(with_table=nil)
-      @result.fetch_hash with_table
-    end
-
-    # Iterate block with record.
-    # @yield [Array] record data
-    # @return [Mysql::Stmt] self
-    # @return [Enumerator] If block is not specified
-    def each(&block)
-      return enum_for(:each) unless block
-      while rec = fetch
-        block.call rec
-      end
-      self
-    end
-
-    # Iterate block with record as Hash.
-    # @param [Boolean] with_table if true, hash key is "table_name.field_name".
-    # @yield [Hash] record data
-    # @return [Mysql::Stmt] self
-    # @return [Enumerator] If block is not specified
-    def each_hash(with_table=nil, &block)
-      return enum_for(:each_hash, with_table) unless block
-      while rec = fetch_hash(with_table)
-        block.call rec
-      end
-      self
-    end
-
-    # @return [Integer] number of record
-    def size
-      @result.size
-    end
-    alias num_rows size
-
-    # Set record position
-    # @param [Integer] n record index
-    # @return [void]
-    def data_seek(n)
-      @result.data_seek(n)
-    end
-
-    # @return [Integer] current record position
-    def row_tell
-      @result.row_tell
-    end
-
-    # Set current position of record
-    # @param [Integer] n record index
-    # @return [Integer] previous position
-    def row_seek(n)
-      @result.row_seek(n)
-    end
-
-    # @return [Integer] number of columns for last query
-    def field_count
-      @fields.length
-    end
-
-    # ignore
-    # @return [void]
-    def free_result
-    end
+  private
 
-    # Returns Mysql::Result object that is empty.
-    # Use fetch_fields to get list of fields.
-    # @return [Mysql::Result]
-    def result_metadata
-      return nil if @fields.empty?
-      Result.new @fields
-    end
+  def check_connection
+    raise ClientError, 'MySQL client is not connected' unless @protocol
   end
 end