ruby-mysql 2.11.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40bdb4e1eba4eca2ed1e93524260bd9407f91ee5f65b8c32b8c38524ef05ebdd
-  data.tar.gz: 224ad0bdf2050dca6e5d7a603bd64cb44a5f414270aa06b9dd89690cd2665a32
+  metadata.gz: 37cc4956fc000b612b24fe104acf96abf27e0a7016cbd05c2c5e7b4ae5e0bade
+  data.tar.gz: b2c4ded73325a5c4aadce1d81af507e2a7d4144764150fde183f0e541e25e8b8
 SHA512:
-  metadata.gz: a73e1ab248a44935cd4115c0d2de16f491d51b2eb7ab7a9b33185a0f478be8753cc226ea78d645a2bb1ae0b09cb15a7432f9e8d5a1dfa82af3ef016783689544
-  data.tar.gz: 37db0a8b13b5a543cf9d552801aa0419c4ccce9fbe287d8df0335002df728e5e5ab5a9d82c873c174dec547b1077730cd265a4a6ace1714c88cb984b3d5f4134
+  metadata.gz: c81163849e312cb8cb861a1c5add93fba0973d1fbf01b9296513914931134230dbf7d2d6437e72097c8426d24daab316c2756621d3302d5ee91efb72ab951cc3
+  data.tar.gz: c4e13cea550e4659db986772663b04364c8c18f51abc9442516058cbe5ebc420dd19a95e324e149ae0966edefa1259fff9274677295849834029f827667547c2

data/CHANGELOG.md

@@ -0,0 +1,58 @@
+## [3.0.1] - 2022-06-18
+
+- LICENSE: correct author
+- FIX: correct LOAD DATA LOCAL INFILE result information.
+- FIX: reset SERVER_MORE_RESULTS_EXISTS when error packet is received.
+- FIX: close the socket when the connection is disconnected.
+- FIX: allow multiple results by default.
+
+## [3.0.0] - 2021-11-16
+
+- `Mysql.new` no longer connect. use `Mysql.connect` or `Mysql#connect`.
+
+- `Mysql.init` is removed. use `Mysql.new` instead.
+
+- `Mysql.new`, `Mysql.conncet` and `Mysql#connect` takes URI object or URI string or Hash object.
+  example:
+      Mysql.connect('mysql://user:password@hostname:port/dbname?charset=ascii')
+      Mysql.connect('mysql://user:password@%2Ftmp%2Fmysql.sock/dbname?charset=ascii') # for UNIX socket
+      Mysql.connect('hostname', 'user', 'password', 'dbname')
+      Mysql.connect(host: 'hostname', username: 'user', password: 'password', database: 'dbname')
+
+- `Mysql.options` is removed. use `Mysql#param = value` instead.
+  For example:
+      m = Mysql.init
+      m.options(Mysql::OPT_LOCAL_INFILE, true)
+      m.connect(host, user, passwd)
+  change to
+      m = Mysql.new
+      m.local_infile = true
+      m.connect(host, user, passwd)
+  or
+      m = Mysql.connect(host, user, passwd, local_infile: true)
+
+- `Mysql::Time` is removed.
+  Instead, `Time` object is returned for the DATE, DATETIME, TIMESTAMP data,
+  and `Integer` object is returned for the TIME data.
+  If DATE, DATETIME, TIMESTAMP are invalid values for Time, nil is returned.
+
+- meaningless methods are removed:
+  * `bind_result`
+  * `client_info`
+  * `client_version`
+  * `get_proto_info`
+  * `get_server_info`
+  * `get_server_version`
+  * `proto_info`
+  * `query_with_result`
+
+- alias method are removed:
+  * `get_host_info`: use `host_info`
+  * `real_connect`: use `connect`
+  * `real_query`: use `query`
+
+- methods corresponding to deprecated APIs in MySQL are removed:
+  * `list_dbs`: use `SHOW DATABASES`
+  * `list_fields`: use `SHOW COLUMNS`
+  * `list_processes`: use `SHOW PROCESSLIST`
+  * `list_tables`: use `SHOW TABLES`

data/README.md

@@ -0,0 +1,28 @@
+# ruby-mysql
+
+## Description
+
+MySQL connector for Ruby.
+
+## Installation
+
+```
+gem install ruby-mysql
+```
+
+## Synopsis
+
+```ruby
+my = Mysql.connect('mysql://username:password@hostname:port/dbname?charset=utf8mb4')
+my.query("select col1, col2 from tblname").each do |col1, col2|
+  p col1, col2
+end
+stmt = my.prepare('insert into tblname (col1,col2) values (?,?)')
+stmt.execute 123, 'abc'
+```
+
+## Copyright
+
+* Author: TOMITA Masahiro <tommy@tmtm.org>
+* Copyright: Copyright 2008 TOMITA Masahiro
+* License: MIT

data/lib/mysql/protocol.rb

@@ -15,12 +15,10 @@ class Mysql
     MAX_PACKET_LENGTH = 2**24-1
 
     # Convert netdata to Ruby value
-    # === Argument
-    # data :: [Packet] packet data
-    # type :: [Integer] field type
-    # unsigned :: [true or false] true if value is unsigned
-    # === Return
-    # Object :: converted value.
+    # @param data [Packet] packet data
+    # @param type [Integer] field type
+    # @param unsigned [true or false] true if value is unsigned
+    # @return [Object] converted value.
     def self.net2value(pkt, type, unsigned)
       case type
       when Field::TYPE_STRING, Field::TYPE_VAR_STRING, Field::TYPE_NEWDECIMAL, Field::TYPE_BLOB, Field::TYPE_JSON
@@ -45,17 +43,18 @@ class Mysql
       when Field::TYPE_DATE
         len = pkt.utiny
         y, m, d = pkt.read(len).unpack("vCC")
-        t = Mysql::Time.new(y, m, d, nil, nil, nil)
+        t = Time.new(y, m, d) rescue nil
         return t
       when Field::TYPE_DATETIME, Field::TYPE_TIMESTAMP
         len = pkt.utiny
         y, m, d, h, mi, s, sp = pkt.read(len).unpack("vCCCCCV")
-        return Mysql::Time.new(y, m, d, h, mi, s, false, sp)
+        return Time.new(y, m, d, h, mi, Rational((s.to_i*1000000+sp.to_i)/1000000)) rescue nil
       when Field::TYPE_TIME
         len = pkt.utiny
         sign, d, h, mi, s, sp = pkt.read(len).unpack("CVCCCV")
-        h = d.to_i * 24 + h.to_i
-        return Mysql::Time.new(0, 0, 0, h, mi, s, sign!=0, sp)
+        r = d.to_i*86400 + h.to_i*3600 + mi.to_i*60 + s.to_i + sp.to_f/1000000
+        r *= -1 if sign != 0
+        return r
       when Field::TYPE_YEAR
         return pkt.ushort
       when Field::TYPE_BIT
@@ -66,13 +65,10 @@ class Mysql
     end
 
     # convert Ruby value to netdata
-    # === Argument
-    # v :: [Object] Ruby value.
-    # === Return
-    # Integer :: type of column. Field::TYPE_*
-    # String :: netdata
-    # === Exception
-    # ProtocolError :: value too large / value is not supported
+    # @param v [Object] Ruby value.
+    # @return [Integer] type of column. Field::TYPE_*
+    # @return [String] netdata
+    # @raise [ProtocolError] value too large / value is not supported
     def self.value2net(v)
       case v
       when nil
@@ -97,12 +93,9 @@ class Mysql
       when String
         type = Field::TYPE_STRING
         val = Packet.lcs(v)
-      when ::Time
+      when Time
         type = Field::TYPE_DATETIME
         val = [11, v.year, v.month, v.day, v.hour, v.min, v.sec, v.usec].pack("CvCCCCCV")
-      when Mysql::Time
-        type = Field::TYPE_DATETIME
-        val = [11, v.year, v.month, v.day, v.hour, v.min, v.sec, v.second_part].pack("CvCCCCCV")
       else
         raise ProtocolError, "class #{v.class} is not supported"
       end
@@ -129,30 +122,38 @@ class Mysql
     # :RESULT :: After retr_fields(), retr_all_records() or stmt_retr_all_records() is needed.
 
     # make socket connection to server.
-    # @param host [String] if "localhost" or "" or nil then use UNIX socket. Otherwise use TCP socket
-    # @param port [Integer] port number using by TCP socket
-    # @param socket [String] socket file name using by UNIX socket
-    # @param [Hash] opts
-    # @option opts :conn_timeout [Integer] connect timeout (sec).
-    # @option opts :read_timeout [Integer] read timeout (sec).
-    # @option opts :write_timeout [Integer] write timeout (sec).
-    # @option opts :local_infile [String] local infile path
-    # @option opts :get_server_public_key [Boolean]
+    # @param opts [Hash]
+    # @option :host [String] hostname mysqld running
+    # @option :username [String] username to connect to mysqld
+    # @option :password [String] password to connect to mysqld
+    # @option :database [String] initial database name
+    # @option :port [String] port number (used if host is not 'localhost' or nil)
+    # @option :socket [String] socket filename (used if host is 'localhost' or nil)
+    # @option :flags [Integer] connection flag. Mysql::CLIENT_* ORed
+    # @option :charset [Mysql::Charset] character set
+    # @option :connect_timeout [Numeric, nil]
+    # @option :read_timeout [Numeric, nil]
+    # @option :write_timeout [Numeric, nil]
+    # @option :local_infile [Boolean]
+    # @option :load_data_local_dir [String]
+    # @option :ssl_mode [Integer]
+    # @option :get_server_public_key [Boolean]
     # @raise [ClientError] connection timeout
-    def initialize(host, port, socket, opts)
+    def initialize(opts)
       @opts = opts
+      @charset = Mysql::Charset.by_name("utf8mb4")
       @insert_id = 0
       @warning_count = 0
       @gc_stmt_queue = []   # stmt id list which GC destroy.
       set_state :INIT
       @get_server_public_key = @opts[:get_server_public_key]
       begin
-        if host.nil? or host.empty? or host == "localhost"
-          socket ||= ENV["MYSQL_UNIX_PORT"] || MYSQL_UNIX_PORT
+        if @opts[:host].nil? or @opts[:host].empty? or @opts[:host] == "localhost"
+          socket = @opts[:socket] || ENV["MYSQL_UNIX_PORT"] || MYSQL_UNIX_PORT
           @socket = Socket.unix(socket)
         else
-          port ||= ENV["MYSQL_TCP_PORT"] || (Socket.getservbyname("mysql","tcp") rescue MYSQL_TCP_PORT)
-          @socket = Socket.tcp(host, port, connect_timeout: @opts[:connect_timeout])
+          port = @opts[:port] || ENV["MYSQL_TCP_PORT"] || (Socket.getservbyname("mysql","tcp") rescue MYSQL_TCP_PORT)
+          @socket = Socket.tcp(@opts[:host], port, connect_timeout: @opts[:connect_timeout])
         end
       rescue Errno::ETIMEDOUT
         raise ClientError, "connection timeout"
@@ -164,45 +165,39 @@ class Mysql
     end
 
     # initial negotiate and authenticate.
-    # === Argument
-    # user    :: [String / nil] username
-    # passwd  :: [String / nil] password
-    # db      :: [String / nil] default database name. nil: no default.
-    # flag    :: [Integer] client flag
-    # charset :: [Mysql::Charset / nil] charset for connection. nil: use server's charset
-    # === Exception
-    # ProtocolError :: The old style password is not supported
-    def authenticate(user, passwd, db, flag, charset)
+    # @param charset [Mysql::Charset, nil] charset for connection. nil: use server's charset
+    # @raise [ProtocolError] The old style password is not supported
+    def authenticate
       check_state :INIT
-      @authinfo = [user, passwd, db, flag, charset]
       reset
       init_packet = InitialPacket.parse read
       @server_info = init_packet.server_version
       @server_version = init_packet.server_version.split(/\D/)[0,3].inject{|a,b|a.to_i*100+b.to_i}
       @server_capabilities = init_packet.server_capabilities
       @thread_id = init_packet.thread_id
-      @client_flags = CLIENT_LONG_PASSWORD | CLIENT_LONG_FLAG | CLIENT_TRANSACTIONS | CLIENT_PROTOCOL_41 | CLIENT_SECURE_CONNECTION | CLIENT_PLUGIN_AUTH
-      @client_flags |= CLIENT_LOCAL_FILES if @opts[:local_infile]
-      @client_flags |= CLIENT_CONNECT_WITH_DB if db
-      @client_flags |= flag
-      @charset = charset
-      unless @charset
+      @client_flags = CLIENT_LONG_PASSWORD | CLIENT_LONG_FLAG | CLIENT_TRANSACTIONS | CLIENT_PROTOCOL_41 | CLIENT_SECURE_CONNECTION | CLIENT_MULTI_RESULTS | CLIENT_PS_MULTI_RESULTS | CLIENT_PLUGIN_AUTH
+      @client_flags |= CLIENT_LOCAL_FILES if @opts[:local_infile] || @opts[:load_data_local_dir]
+      @client_flags |= CLIENT_CONNECT_WITH_DB if @opts[:database]
+      @client_flags |= @opts[:flags]
+      if @opts[:charset]
+        @charset = @opts[:charset].is_a?(Charset) ? @opts[:charset] : Charset.by_name(@opts[:charset])
+      else
         @charset = Charset.by_number(init_packet.server_charset)
         @charset.encoding       # raise error if unsupported charset
       end
       enable_ssl
-      Authenticator.new(self).authenticate(user, passwd, db, init_packet.scramble_buff, init_packet.auth_plugin)
+      Authenticator.new(self).authenticate(@opts[:username], @opts[:password].to_s, @opts[:database], init_packet.scramble_buff, init_packet.auth_plugin)
       set_state :READY
     end
 
     def enable_ssl
       case @opts[:ssl_mode]
-      when SSL_MODE_DISABLED
+      when SSL_MODE_DISABLED, '1', 'disabled'
         return
-      when SSL_MODE_PREFERRED
+      when SSL_MODE_PREFERRED, '2', 'preferred'
         return if @socket.local_address.unix?
         return if @server_capabilities & CLIENT_SSL == 0
-      when SSL_MODE_REQUIRED
+      when SSL_MODE_REQUIRED, '3', 'required'
         if @server_capabilities & CLIENT_SSL == 0
           raise ClientError::SslConnectionError, "SSL is required but the server doesn't support it"
         end
@@ -232,10 +227,8 @@ class Mysql
     end
 
     # Query command
-    # === Argument
-    # query :: [String] query string
-    # === Return
-    # [Integer / nil] number of fields of results. nil if no results.
+    # @param query [String] query string
+    # @return [Integer, nil] number of fields of results. nil if no results.
     def query_command(query)
       check_state :READY
       begin
@@ -249,8 +242,7 @@ class Mysql
     end
 
     # get result of query.
-    # === Return
-    # [integer / nil] number of fields of results. nil if no results.
+    # @return [integer, nil] number of fields of results. nil if no results.
     def get_result
       begin
         res_packet = ResultPacket.parse read
@@ -260,6 +252,7 @@ class Mysql
         end
         if res_packet.field_count.nil?      # LOAD DATA LOCAL INFILE
           send_local_file(res_packet.message)
+          res_packet = ResultPacket.parse read
         end
         @affected_rows, @insert_id, @server_status, @warning_count, @message =
           res_packet.affected_rows, res_packet.insert_id, res_packet.server_status, res_packet.warning_count, res_packet.message
@@ -274,21 +267,18 @@ class Mysql
     # send local file to server
     def send_local_file(filename)
       filename = File.absolute_path(filename)
-      if filename.start_with? @opts[:local_infile]
+      if @opts[:local_infile] || @opts[:load_data_local_dir] && filename.start_with?(@opts[:load_data_local_dir])
         File.open(filename){|f| write f}
       else
         raise ClientError::LoadDataLocalInfileRejected, 'LOAD DATA LOCAL INFILE file request rejected due to restrictions on access.'
       end
     ensure
       write nil # EOF mark
-      read
     end
 
     # Retrieve n fields
-    # === Argument
-    # n :: [Integer] number of fields
-    # === Return
-    # [Array of Mysql::Field] field list
+    # @param n [Integer] number of fields
+    # @return [Array<Mysql::Field>] field list
     def retr_fields(n)
       check_state :FIELD
       begin
@@ -303,10 +293,8 @@ class Mysql
     end
 
     # Retrieve all records for simple query
-    # === Argument
-    # fields :: [Array<Mysql::Field>] number of fields
-    # === Return
-    # [Array of Array of String] all records
+    # @param fields [Array<Mysql::Field>] number of fields
+    # @return [Array<Array<String>>] all records
     def retr_all_records(fields)
       check_state :RESULT
       enc = charset.encoding
@@ -323,43 +311,6 @@ class Mysql
       end
     end
 
-    # Field list command
-    # === Argument
-    # table :: [String] table name.
-    # field :: [String / nil] field name that may contain wild card.
-    # === Return
-    # [Array of Field] field list
-    def field_list_command(table, field)
-      synchronize do
-        reset
-        write [COM_FIELD_LIST, table, 0, field].pack("Ca*Ca*")
-        fields = []
-        until (data = read).eof?
-          fields.push Field.new(FieldPacket.parse(data))
-        end
-        return fields
-      end
-    end
-
-    # Process info command
-    # === Return
-    # [Array of Field] field list
-    def process_info_command
-      check_state :READY
-      begin
-        reset
-        write [COM_PROCESS_INFO].pack("C")
-        field_count = read.lcb
-        fields = field_count.times.map{Field.new FieldPacket.parse(read)}
-        read_eof_packet
-        set_state :RESULT
-        return fields
-      rescue
-        set_state :READY
-        raise
-      end
-    end
-
     # Ping command
     def ping_command
       simple_command [COM_PING].pack("C")
@@ -391,12 +342,8 @@ class Mysql
     end
 
     # Stmt prepare command
-    # === Argument
-    # stmt :: [String] prepared statement
-    # === Return
-    # [Integer] statement id
-    # [Integer] number of parameters
-    # [Array of Field] field list
+    # @param stmt [String] prepared statement
+    # @return [Array<Integer, Integer, Array<Field>>] statement id, number of parameters, field list
     def stmt_prepare_command(stmt)
       synchronize do
         reset
@@ -417,11 +364,9 @@ class Mysql
     end
 
     # Stmt execute command
-    # === Argument
-    # stmt_id :: [Integer] statement id
-    # values  :: [Array] parameters
-    # === Return
-    # [Integer] number of fields
+    # @param stmt_id [Integer] statement id
+    # @param values [Array] parameters
+    # @return [Integer] number of fields
     def stmt_execute_command(stmt_id, values)
       check_state :READY
       begin
@@ -435,11 +380,9 @@ class Mysql
     end
 
     # Retrieve all records for prepared statement
-    # === Argument
-    # fields  :: [Array of Mysql::Fields] field list
-    # charset :: [Mysql::Charset]
-    # === Return
-    # [Array of Array of Object] all records
+    # @param fields [Array of Mysql::Fields] field list
+    # @param charset [Mysql::Charset]
+    # @return [Array<Array<Object>>] all records
     def stmt_retr_all_records(fields, charset)
       check_state :RESULT
       enc = charset.encoding
@@ -455,8 +398,7 @@ class Mysql
     end
 
     # Stmt close command
-    # === Argument
-    # stmt_id :: [Integer] statement id
+    # @param stmt_id [Integer] statement id
     def stmt_close_command(stmt_id)
       synchronize do
         reset
@@ -502,10 +444,8 @@ class Mysql
     end
 
     # Read one packet data
-    # === Return
-    # [Packet] packet data
-    # === Exception
-    # [ProtocolError] invalid packet sequence number
+    # @return [Packet] packet data
+    # @rails [ProtocolError] invalid packet sequence number
     def read
       data = ''
       len = nil
@@ -520,6 +460,7 @@ class Mysql
         raise EOFError unless ret && ret.length == len
         data.concat ret
       rescue EOFError
+        @socket.close rescue nil
         raise ClientError::ServerGoneError, 'MySQL server has gone away'
       rescue Errno::ETIMEDOUT
         raise ClientError, "read timeout"
@@ -534,6 +475,7 @@ class Mysql
           _, errno, message = data.unpack("Cva*")    # Version 4.0 Error
           @sqlstate = ""
         end
+        @server_status &= ~SERVER_MORE_RESULTS_EXISTS
         message.force_encoding(@charset.encoding)
         if Mysql::ServerError::ERROR_MAP.key? errno
           raise Mysql::ServerError::ERROR_MAP[errno].new(message, @sqlstate)
@@ -546,9 +488,9 @@ class Mysql
     def read_timeout(len, timeout)
       return @socket.read(len) if timeout.nil? || timeout == 0
       result = ''
-      e = ::Time.now + timeout
+      e = Time.now + timeout
       while result.size < len
-        now = ::Time.now
+        now = Time.now
         raise Errno::ETIMEDOUT if now > e
         r = @socket.read_nonblock(len - result.size, exception: false)
         case r
@@ -566,8 +508,7 @@ class Mysql
     end
 
     # Write one packet data
-    # === Argument
-    # data :: [String / IO] packet data. If data is nil, write empty packet.
+    # @param data [String, IO, nil] packet data. If data is nil, write empty packet.
     def write(data)
       begin
         @socket.sync = false
@@ -584,6 +525,7 @@ class Mysql
         @socket.sync = true
         @socket.flush
       rescue Errno::EPIPE
+        @socket.close rescue nil
         raise ClientError::ServerGoneError, 'MySQL server has gone away'
       rescue Errno::ETIMEDOUT
         raise ClientError, "write timeout"
@@ -593,9 +535,9 @@ class Mysql
     def write_timeout(data, timeout)
       return @socket.write(data) if timeout.nil? || timeout == 0
       len = 0
-      e = ::Time.now + timeout
+      e = Time.now + timeout
       while len < data.size
-        now = ::Time.now
+        now = Time.now
         raise Errno::ETIMEDOUT if now > e
         l = @socket.write_nonblock(data[len..-1], exception: false)
         case l
@@ -611,17 +553,14 @@ class Mysql
     end
 
     # Read EOF packet
-    # === Exception
-    # [ProtocolError] packet is not EOF
+    # @raise [ProtocolError] packet is not EOF
     def read_eof_packet
       raise ProtocolError, "packet is not EOF" unless read.eof?
     end
 
     # Send simple command
-    # === Argument
-    # packet :: [String] packet data
-    # === Return
-    # [String] received data
+    # @param packet :: [String] packet data
+    # @return [String] received data
     def simple_command(packet)
       synchronize do
         reset
@@ -831,17 +770,15 @@ class Mysql
   end
 
   class StmtRawRecord
-    # === Argument
-    # pkt     :: [Packet]
-    # fields  :: [Array of Fields]
-    # encoding:: [Encoding]
+    # @param pkt [Packet]
+    # @param fields [Array of Fields]
+    # @param encoding [Encoding]
     def initialize(packet, fields, encoding)
       @packet, @fields, @encoding = packet, fields, encoding
     end
 
     # Parse statement result packet
-    # === Return
-    # [Array of Object] one record
+    # @return [Array<Object>] one record
     def parse_record_packet
       @packet.utiny  # skip first byte
       null_bit_map = @packet.read((@fields.length+7+2)/8).unpack("b*").first
@@ -851,7 +788,7 @@ class Mysql
         else
           unsigned = f.flags & Field::UNSIGNED_FLAG != 0
           v = Protocol.net2value(@packet, f.type, unsigned)
-          if v.is_a? Numeric or v.is_a? Mysql::Time
+          if v.nil? or v.is_a? Numeric or v.is_a? Time
             v
           elsif f.type == Field::TYPE_BIT or f.charsetnr == Charset::BINARY_CHARSET_NUMBER
             Charset.to_binary(v)