ruby-mysql 2.9.14 → 3.0.0

data/lib/mysql.rb

@@ -1,7 +1,9 @@
 # coding: ascii-8bit
-# Copyright (C) 2008-2012 TOMITA Masahiro
+# Copyright (C) 2008 TOMITA Masahiro
 # mailto:tommy@tmtm.org
 
+require 'uri'
+
 # MySQL connection class.
 # @example
 #  my = Mysql.connect('hostname', 'user', 'password', 'dbname')
@@ -11,48 +13,76 @@
 #  end
 class Mysql
 
-  require "mysql/constants"
-  require "mysql/error"
-  require "mysql/charset"
-  require "mysql/protocol"
-  require "mysql/packet.rb"
-  begin
-    require "mysql/ext.so"
-  rescue LoadError
-  end
+  require_relative "mysql/constants"
+  require_relative "mysql/error"
+  require_relative "mysql/charset"
+  require_relative "mysql/protocol"
+  require_relative "mysql/packet.rb"
 
-  VERSION            = 20913               # Version number of this library
+  VERSION            = '3.0.0'             # Version number of this library
   MYSQL_UNIX_PORT    = "/tmp/mysql.sock"   # UNIX domain socket filename
   MYSQL_TCP_PORT     = 3306                # TCP socket port number
 
-  # @return [Mysql::Charset] character set of MySQL connection
-  attr_reader :charset
+  # @!attribute [rw] host
+  #   @return [String, nil]
+  # @!attribute [rw] username
+  #   @return [String, nil]
+  # @!attribute [rw] password
+  #   @return [String, nil]
+  # @!attribute [rw] database
+  #   @return [String, nil]
+  # @!attribute [rw] port
+  #   @return [Integer, String, nil]
+  # @!attribute [rw] socket
+  #   @return [String, nil] socket filename
+  # @!attribute [rw] flags
+  #   @return [Integer, nil]
+  # @!attribute [rw] connect_timeout
+  #   @return [Numeric, nil]
+  # @!attribute [rw] read_timeout
+  #   @return [Numeric, nil]
+  # @!attribute [rw] write_timeout
+  #   @return [Numeric, nil]
+  # @!attribute [rw] init_command
+  #   @return [String, nil]
+  # @!attribute [rw] local_infile
+  #   @return [Boolean]
+  # @!attribute [rw] load_data_local_dir
+  #   @return [String, nil]
+  # @!attribute [rw] ssl_mode
+  #   @return [String, Integer] 1 or "disabled" / 2 or "preferred" / 3 or "required"
+  # @!attribute [rw] get_server_public_key
+  #   @return [Boolean]
+  DEFAULT_OPTS = {
+    host: nil,
+    username: nil,
+    password: nil,
+    database: nil,
+    port: nil,
+    socket: nil,
+    flags: 0,
+    charset: nil,
+    connect_timeout: nil,
+    read_timeout: nil,
+    write_timeout: nil,
+    init_command: nil,
+    local_infile: nil,
+    load_data_local_dir: nil,
+    ssl_mode: SSL_MODE_PREFERRED,
+    get_server_public_key: false,
+  }.freeze
+
   # @private
   attr_reader :protocol
 
-  # @return [Boolean] if true, {#query} return {Mysql::Result}.
-  attr_accessor :query_with_result
-
   class << self
-    # Make Mysql object without connecting.
-    # @return [Mysql]
-    def init
-      my = self.allocate
-      my.instance_eval{initialize}
-      my
-    end
-
     # Make Mysql object and connect to mysqld.
-    # @param args same as arguments for {#connect}.
+    # parameter is same as arguments for {#initialize}.
     # @return [Mysql]
-    def new(*args)
-      my = self.init
-      my.connect(*args)
+    def connect(*args, **opts)
+      self.new(*args, **opts).connect
     end
 
-    alias real_connect new
-    alias connect new
-
     # Escape special character in string.
     # @param [String] str
     # @return [String]
@@ -68,58 +98,116 @@ class Mysql
       end
     end
     alias quote escape_string
-
-    # @return [String] client version. This value is dummy for MySQL/Ruby compatibility.
-    def client_info
-      "5.0.0"
-    end
-    alias get_client_info client_info
-
-    # @return [Integer] client version. This value is dummy for MySQL/Ruby compatibility.
-    def client_version
-      50000
-    end
-    alias get_client_version client_version
   end
 
-  def initialize
+  # @overload initialize(uri, **opts)
+  #   @param uri [String, URI] "mysql://username:password@host:port/database?param=value&..." / "mysql://username:password@%2Ftmp%2Fmysql.sock/database" / "mysql://username:password@/database?socket=/tmp/mysql.sock"
+  #   @param opts [Hash] options
+  # @overload initialize(host, username, password, database, port, socket, flags, **opts)
+  #   @param host [String] hostname mysqld running
+  #   @param username [String] username to connect to mysqld
+  #   @param password [String] password to connect to mysqld
+  #   @param database [String] initial database name
+  #   @param port [String] port number (used if host is not 'localhost' or nil)
+  #   @param socket [String] socket filename (used if host is 'localhost' or nil)
+  #   @param flags [Integer] connection flag. Mysql::CLIENT_* ORed
+  #   @param opts [Hash] options
+  # @overload initialize(host: nil, username: nil, password: nil, database: nil, port: nil, socket: nil, flags: nil, **opts)
+  #   @param host [String] hostname mysqld running
+  #   @param username [String] username to connect to mysqld
+  #   @param password [String] password to connect to mysqld
+  #   @param database [String] initial database name
+  #   @param port [String] port number (used if host is not 'localhost' or nil)
+  #   @param socket [String] socket filename (used if host is 'localhost' or nil)
+  #   @param flags [Integer] connection flag. Mysql::CLIENT_* ORed
+  #   @param opts [Hash] options
+  #   @option opts :host [String] hostname mysqld running
+  #   @option opts :username [String] username to connect to mysqld
+  #   @option opts :password [String] password to connect to mysqld
+  #   @option opts :database [String] initial database name
+  #   @option opts :port [String] port number (used if host is not 'localhost' or nil)
+  #   @option opts :socket [String] socket filename (used if host is 'localhost' or nil)
+  #   @option opts :flags [Integer] connection flag. Mysql::CLIENT_* ORed
+  #   @option opts :charset [Mysql::Charset, String] character set
+  #   @option opts :connect_timeout [Numeric, nil]
+  #   @option opts :read_timeout [Numeric, nil]
+  #   @option opts :write_timeout [Numeric, nil]
+  #   @option opts :local_infile [Boolean]
+  #   @option opts :load_data_local_dir [String]
+  #   @option opts :ssl_mode [Integer]
+  #   @option opts :get_server_public_key [Boolean]
+  def initialize(*args, **opts)
     @fields = nil
     @protocol = nil
-    @charset = nil
-    @connect_timeout = nil
-    @read_timeout = nil
-    @write_timeout = nil
-    @init_command = nil
     @sqlstate = "00000"
-    @query_with_result = true
     @host_info = nil
     @last_error = nil
     @result_exist = false
-    @local_infile = nil
+    @opts = DEFAULT_OPTS.dup
+    parse_args(args, opts)
   end
 
   # Connect to mysqld.
-  # @param [String / nil] host hostname mysqld running
-  # @param [String / nil] user username to connect to mysqld
-  # @param [String / nil] passwd password to connect to mysqld
-  # @param [String / nil] db initial database name
-  # @param [Integer / nil] port port number (used if host is not 'localhost' or nil)
-  # @param [String / nil] socket socket file name (used if host is 'localhost' or nil)
-  # @param [Integer / nil] flag connection flag. Mysql::CLIENT_* ORed
-  # @return self
-  def connect(host=nil, user=nil, passwd=nil, db=nil, port=nil, socket=nil, flag=0)
-    if flag & CLIENT_COMPRESS != 0
+  # parameter is same as arguments for {#initialize}.
+  # @return [Mysql] self
+  def connect(*args, **opts)
+    parse_args(args, opts)
+    if @opts[:flags] & CLIENT_COMPRESS != 0
       warn 'unsupported flag: CLIENT_COMPRESS' if $VERBOSE
-      flag &= ~CLIENT_COMPRESS
+      @opts[:flags] &= ~CLIENT_COMPRESS
     end
-    @protocol = Protocol.new host, port, socket, @connect_timeout, @read_timeout, @write_timeout
-    @protocol.authenticate user, passwd, db, (@local_infile ? CLIENT_LOCAL_FILES : 0) | flag, @charset
-    @charset ||= @protocol.charset
-    @host_info = (host.nil? || host == "localhost") ? 'Localhost via UNIX socket' : "#{host} via TCP/IP"
-    query @init_command if @init_command
+    @protocol = Protocol.new(@opts)
+    @protocol.authenticate
+    @host_info = (@opts[:host].nil? || @opts[:host] == "localhost") ? 'Localhost via UNIX socket' : "#{@opts[:host]} via TCP/IP"
+    query @opts[:init_command] if @opts[:init_command]
     return self
   end
-  alias real_connect connect
+
+  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
+    end
+    if uri
+      host = uri.hostname.to_s
+      host = URI.decode_www_form_component(host)
+      if host.start_with?('/')
+        @opts[:socket] = host
+        host = ''
+      end
+      @opts[:host] = host
+      @opts[:username] = URI.decode_www_form_component(uri.user.to_s)
+      @opts[:password] = URI.decode_www_form_component(uri.password.to_s)
+      @opts[:database] = uri.path.sub(/\A\/+/, '')
+      @opts[:port] = uri.port
+      opts = URI.decode_www_form(uri.query).to_h.transform_keys(&:intern).merge(opts) if uri.query
+      opts[:flags] = opts[:flags].to_i if opts[:flags]
+    end
+    if args.last.kind_of? Hash
+      opts = opts.merge(args.last)
+    end
+    @opts.update(opts)
+  end
+
+  DEFAULT_OPTS.each_key do |var|
+    next if var == :charset
+    define_method(var){@opts[var]}
+    define_method("#{var}="){|val| @opts[var] = val}
+  end
 
   # Disconnect from mysql.
   # @return [Mysql] self
@@ -141,90 +229,35 @@ class Mysql
     return self
   end
 
-  # Set option for connection.
-  #
-  # Available options:
-  #   Mysql::INIT_COMMAND, Mysql::OPT_CONNECT_TIMEOUT, Mysql::OPT_READ_TIMEOUT,
-  #   Mysql::OPT_WRITE_TIMEOUT, Mysql::SET_CHARSET_NAME
-  # @param [Integer] opt option
-  # @param [Integer] value option value that is depend on opt
-  # @return [Mysql] self
-  def options(opt, value=nil)
-    case opt
-    when Mysql::INIT_COMMAND
-      @init_command = value.to_s
-#    when Mysql::OPT_COMPRESS
-    when Mysql::OPT_CONNECT_TIMEOUT
-      @connect_timeout = value
-#    when Mysql::GUESS_CONNECTION
-    when Mysql::OPT_LOCAL_INFILE
-      @local_infile = value
-#    when Mysql::OPT_NAMED_PIPE
-#    when Mysql::OPT_PROTOCOL
-    when Mysql::OPT_READ_TIMEOUT
-      @read_timeout = value.to_i
-#    when Mysql::OPT_RECONNECT
-#    when Mysql::SET_CLIENT_IP
-#    when Mysql::OPT_SSL_VERIFY_SERVER_CERT
-#    when Mysql::OPT_USE_EMBEDDED_CONNECTION
-#    when Mysql::OPT_USE_REMOTE_CONNECTION
-    when Mysql::OPT_WRITE_TIMEOUT
-      @write_timeout = value.to_i
-#    when Mysql::READ_DEFAULT_FILE
-#    when Mysql::READ_DEFAULT_GROUP
-#    when Mysql::REPORT_DATA_TRUNCATION
-#    when Mysql::SECURE_AUTH
-#    when Mysql::SET_CHARSET_DIR
-    when Mysql::SET_CHARSET_NAME
-      @charset = Charset.by_name value.to_s
-#    when Mysql::SHARED_MEMORY_BASE_NAME
-    else
-      warn "option not implemented: #{opt}" if $VERBOSE
-    end
-    self
-  end
-
   # Escape special character in MySQL.
   #
-  # In Ruby 1.8, this is not safe for multibyte charset such as 'SJIS'.
-  # You should use place-holder in prepared-statement.
   # @param [String] str
   # return [String]
   def escape_string(str)
-    if not defined? Encoding and @charset.unsafe
-      raise ClientError, 'Mysql#escape_string is called for unsafe multibyte charset'
-    end
     self.class.escape_string str
   end
   alias quote escape_string
 
-  # @return [String] client version
-  def client_info
-    self.class.client_info
-  end
-  alias get_client_info client_info
-
-  # @return [Integer] client version
-  def client_version
-    self.class.client_version
+  # @return [Mysql::Charset] character set of MySQL connection
+  def charset
+    @opts[:charset]
   end
-  alias get_client_version client_version
 
   # Set charset of MySQL connection.
-  # @param [String / Mysql::Charset] cs
+  # @param [String, Mysql::Charset] cs
   def charset=(cs)
     charset = cs.is_a?(Charset) ? cs : Charset.by_name(cs)
     if @protocol
       @protocol.charset = charset
       query "SET NAMES #{charset.name}"
     end
-    @charset = charset
+    @opts[:charset] = charset
     cs
   end
 
   # @return [String] charset name
   def character_set_name
-    @charset.name
+    @protocol.charset.name
   end
 
   # @return [Integer] last error number
@@ -251,27 +284,18 @@ class Mysql
   def host_info
     @host_info
   end
-  alias get_host_info host_info
-
-  # @return [Integer] protocol version
-  def proto_info
-    Mysql::Protocol::VERSION
-  end
-  alias get_proto_info proto_info
 
   # @return [String] server version
   def server_info
     check_connection
     @protocol.server_info
   end
-  alias get_server_info server_info
 
   # @return [Integer] server version
   def server_version
     check_connection
     @protocol.server_version
   end
-  alias get_server_version server_version
 
   # @return [String] information for last query
   def info
@@ -302,22 +326,18 @@ class Mysql
     self
   end
 
-  # database list.
-  # @param [String] db database name that may contain wild card.
-  # @return [Array<String>] database list
-  def list_dbs(db=nil)
-    db &&= db.gsub(/[\\\']/){"\\#{$&}"}
-    query(db ? "show databases like '#{db}'" : "show databases").map(&:first)
-  end
-
   # Execute query string.
-  # @param [String] str Query.
-  # @yield [Mysql::Result] evaluated per query.
-  # @return [Mysql::Result] If {#query_with_result} is true and result set exist.
-  # @return [nil] If {#query_with_result} is true and the query does not return result set.
-  # @return [Mysql] If {#query_with_result} is false or block is specified
+  # @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]
   # @example
   #  my.query("select 1,NULL,'abc'").fetch  # => [1, nil, "abc"]
+  #  my.query("select 1,NULL,'abc'"){|res| res.fetch}
   def query(str, &block)
     check_connection
     @fields = nil
@@ -334,20 +354,15 @@ class Mysql
         end
         return self
       end
-      if @query_with_result
-        return @fields ? store_result : nil
-      else
-        return self
-      end
+      return @fields ? store_result : nil
     rescue ServerError => e
       @last_error = e
       @sqlstate = e.sqlstate
       raise
     end
   end
-  alias real_query query
 
-  # Get all data for last query if query_with_result is false.
+  # Get all data for last query.
   # @return [Mysql::Result]
   def store_result
     check_connection
@@ -363,12 +378,6 @@ class Mysql
     @protocol.thread_id
   end
 
-  # Use result of query. The result data is retrieved when you use Mysql::Result#fetch.
-  # @return [Mysql::Result]
-  def use_result
-    store_result
-  end
-
   # Set server option.
   # @param [Integer] opt {Mysql::OPTION_MULTI_STATEMENTS_ON} or {Mysql::OPTION_MULTI_STATEMENTS_OFF}
   # @return [Mysql] self
@@ -402,7 +411,7 @@ class Mysql
   # @param [String] str query string
   # @return [Mysql::Stmt] Prepared-statement object
   def prepare(str)
-    st = Stmt.new @protocol, @charset
+    st = Stmt.new @protocol
     st.prepare str
     st
   end
@@ -410,41 +419,8 @@ class Mysql
   # @private
   # Make empty prepared-statement object.
   # @return [Mysql::Stmt] If block is not specified.
-  def stmt_init
-    Stmt.new @protocol, @charset
-  end
-
-  # Returns Mysql::Result object that is empty.
-  # Use fetch_fields to get list of fields.
-  # @param [String] table table name.
-  # @param [String] field field name that may contain wild card.
-  # @return [Mysql::Result]
-  def list_fields(table, field=nil)
-    check_connection
-    begin
-      fields = @protocol.field_list_command table, field
-      return Result.new fields
-    rescue ServerError => e
-      @last_error = e
-      @sqlstate = e.sqlstate
-      raise
-    end
-  end
-
-  # @return [Mysql::Result] containing process list
-  def list_processes
-    check_connection
-    @fields = @protocol.process_info_command
-    @result_exist = true
-    store_result
-  end
-
-  # @note for Ruby 1.8: This is not multi-byte safe. Don't use for multi-byte charset such as cp932.
-  # @param [String] table database name that may contain wild card.
-  # @return [Array<String>] list of table name.
-  def list_tables(table=nil)
-    q = table ? "show tables like '#{quote table}'" : "show tables"
-    query(q).map(&:first)
+  def stmt
+    Stmt.new @protocol
   end
 
   # Check whether the  connection is available.
@@ -557,7 +533,7 @@ class Mysql
     end
 
     # @return [Hash] field information
-    def hash
+    def to_hash
       {
         "name"       => @name,
         "table"      => @table,
@@ -793,10 +769,9 @@ class Mysql
     # @private
     # @param [Array<Mysql::Field>] fields
     # @param [Mysql::Protocol] protocol
-    # @param [Mysql::Charset] charset
-    def initialize(fields, protocol, charset)
+    def initialize(fields, protocol)
       super fields
-      @records = protocol.stmt_retr_all_records @fields, charset
+      @records = protocol.stmt_retr_all_records @fields, protocol.charset
     end
   end
 
@@ -831,15 +806,12 @@ class Mysql
 
     # @private
     # @param [Mysql::Protocol] protocol
-    # @param [Mysql::Charset] charset
-    def initialize(protocol, charset)
+    def initialize(protocol)
       @protocol = protocol
-      @charset = charset
       @statement_id = nil
       @affected_rows = @insert_id = @server_status = @warning_count = 0
       @sqlstate = "00000"
       @param_count = nil
-      @bind_result = nil
     end
 
     # @private
@@ -866,13 +838,13 @@ class Mysql
     def execute(*values)
       raise ClientError, "not prepared" unless @param_count
       raise ClientError, "parameter count mismatch" if values.length != @param_count
-      values = values.map{|v| @charset.convert v}
+      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, @charset
+          @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
@@ -895,46 +867,7 @@ class Mysql
 
     # @return [Array] current record data
     def fetch
-      row = @result.fetch
-      return row unless @bind_result
-      row.zip(@bind_result).map do |col, type|
-        if col.nil?
-          nil
-        elsif [Numeric, Integer, Fixnum].include? type
-          col.to_i
-        elsif type == String
-          col.to_s
-        elsif type == Float && !col.is_a?(Float)
-          col.to_i.to_f
-        elsif type == Mysql::Time && !col.is_a?(Mysql::Time)
-          if col.to_s =~ /\A\d+\z/
-            i = col.to_s.to_i
-            if i < 100000000
-              y = i/10000
-              m = i/100%100
-              d = i%100
-              h, mm, s = 0
-            else
-              y = i/10000000000
-              m = i/100000000%100
-              d = i/1000000%100
-              h = i/10000%100
-              mm= i/100%100
-              s = i%100
-            end
-            if y < 70
-              y += 2000
-            elsif y < 100
-              y += 1900
-            end
-            Mysql::Time.new(y, m, d, h, mm, s)
-          else
-            Mysql::Time.new
-          end
-        else
-          col
-        end
-      end
+      @result.fetch
     end
 
     # Return data of current record as Hash.
@@ -945,20 +878,6 @@ class Mysql
       @result.fetch_hash with_table
     end
 
-    # Set retrieve type of value
-    # @param [Numeric / Fixnum / Integer / Float / String / Mysql::Time / nil] args value type
-    # @return [Mysql::Stmt] self
-    def bind_result(*args)
-      if @fields.length != args.length
-        raise ClientError, "bind_result: result value count(#{@fields.length}) != number of argument(#{args.length})"
-      end
-      args.each do |a|
-        raise TypeError unless [Numeric, Fixnum, Integer, Float, String, Mysql::Time, nil].include? a
-      end
-      @bind_result = args
-      self
-    end
-
     # Iterate block with record.
     # @yield [Array] record data
     # @return [Mysql::Stmt] self
@@ -1027,78 +946,4 @@ class Mysql
       Result.new @fields
     end
   end
-
-  # @!visibility public
-  # @!attribute [rw] year
-  #   @return [Integer]
-  # @!attribute [rw] month
-  #   @return [Integer]
-  # @!attribute [rw] day
-  #   @return [Integer]
-  # @!attribute [rw] hour
-  #   @return [Integer]
-  # @!attribute [rw] minute
-  #   @return [Integer]
-  # @!attribute [rw] second
-  #   @return [Integer]
-  # @!attribute [rw] neg
-  #   @return [Boolean] negative flag
-  # @!attribute [rw] second_part
-  #   @return [Integer]
-  class Time
-    # @param [Integer] year
-    # @param [Integer] month
-    # @param [Integer] day
-    # @param [Integer] hour
-    # @param [Integer] minute
-    # @param [Integer] second
-    # @param [Boolean] neg negative flag
-    # @param [Integer] second_part
-    def initialize(year=0, month=0, day=0, hour=0, minute=0, second=0, neg=false, second_part=0)
-      @date_flag = !(hour && minute && second)
-      @year, @month, @day, @hour, @minute, @second, @neg, @second_part =
-        year.to_i, month.to_i, day.to_i, hour.to_i, minute.to_i, second.to_i, neg, second_part.to_i
-    end
-    attr_accessor :year, :month, :day, :hour, :minute, :second, :neg, :second_part
-    alias mon month
-    alias min minute
-    alias sec second
-
-    # @private
-    def ==(other)
-      other.is_a?(Mysql::Time) &&
-        @year == other.year && @month == other.month && @day == other.day &&
-        @hour == other.hour && @minute == other.minute && @second == other.second &&
-        @neg == neg && @second_part == other.second_part
-    end
-
-    # @private
-    def eql?(other)
-      self == other
-    end
-
-    # @return [String] "yyyy-mm-dd HH:MM:SS"
-    def to_s
-      if @date_flag
-        sprintf "%04d-%02d-%02d", year, mon, day
-      elsif year == 0 and mon == 0 and day == 0
-        h = neg ? hour * -1 : hour
-        sprintf "%02d:%02d:%02d", h, min, sec
-      else
-        sprintf "%04d-%02d-%02d %02d:%02d:%02d", year, mon, day, hour, min, sec
-      end
-    end
-
-    # @return [Integer] yyyymmddHHMMSS
-    def to_i
-      sprintf("%04d%02d%02d%02d%02d%02d", year, mon, day, hour, min, sec).to_i
-    end
-
-    # @private
-    def inspect
-      sprintf "#<#{self.class.name}:%04d-%02d-%02d %02d:%02d:%02d>", year, mon, day, hour, min, sec
-    end
-
-  end
-
 end