ruby-mysql 2.11.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 178673e0e53a16263b882308afca1831d674e96057828c2115d34ec3669dc58e
-  data.tar.gz: 23e9fc852a81f976f1d8130fbcd0c623dc234c8e741e60c0fd58094079fb02bd
+  metadata.gz: f95fb29b93c207b23bbc1378ce78b10ab297269f0cf24409116a69502cdf9ae8
+  data.tar.gz: 7979ccfd21194e81a4c98f90920b7dc3cdb1165201bdf7bc0d640d16fbe8ebea
 SHA512:
-  metadata.gz: dc51341a75ae3373d2b375632781809abc68ac30fbee593761b67a304ef33b3d52538762dfd144f5ddad0b63416b68c0f9ce1f68ab89228f0f5b0e4f82a2332f
-  data.tar.gz: 8ee78f4d06f1714b2c0cb83537b3efe643e968a212c64c71cd3e19dda422a4f9961a16578dab45d1c43f147a2551d7499447645576a6545698e00419c5cae7c9
+  metadata.gz: '068b6f6008f4b77dc6d34b660c8f06b73db2c06e63fc98d69d5455ceb6ab61c3924d158de4398d6b897cc2fa44d460a879b60355dbb16ac90f0af666f750467d'
+  data.tar.gz: 769105fbd5f16a4b8ab9c55c4a1243c962db3a238f05baa16d970cb2cbaadba0f0487c2daf194b53ce0bfa48639aac37cb79527da02518607a4a0a861cdd6caf

data/CHANGELOG.md

@@ -0,0 +1,50 @@
+## [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,17 +165,10 @@ 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
@@ -182,27 +176,28 @@ class Mysql
       @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_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
@@ -274,7 +266,7 @@ 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.'
@@ -285,10 +277,8 @@ class Mysql
     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
@@ -546,9 +486,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 +506,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
@@ -593,9 +532,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 +550,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 +767,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 +785,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)