ruby-mysql 3.0.1 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37cc4956fc000b612b24fe104acf96abf27e0a7016cbd05c2c5e7b4ae5e0bade
-  data.tar.gz: b2c4ded73325a5c4aadce1d81af507e2a7d4144764150fde183f0e541e25e8b8
+  metadata.gz: fd37c2f40ef7277952c0be41848abc338e29d3a4e9da3f3eed1d1d8f61407c76
+  data.tar.gz: 754994f1cb1f5e4cb007d5f1a3d81238e626ce8d224aef23c58c8af3d5fd351f
 SHA512:
-  metadata.gz: c81163849e312cb8cb861a1c5add93fba0973d1fbf01b9296513914931134230dbf7d2d6437e72097c8426d24daab316c2756621d3302d5ee91efb72ab951cc3
-  data.tar.gz: c4e13cea550e4659db986772663b04364c8c18f51abc9442516058cbe5ebc420dd19a95e324e149ae0966edefa1259fff9274677295849834029f827667547c2
+  metadata.gz: c31c8170682621713905f820a2816377a045b3ba489adc39d3575543483475411bdd7ecead30f806494533dd91819e8e53dad1bd3c090164b80d7600666ea1a4
+  data.tar.gz: 6f59d7638d0f09bd3c21cd34e32cae9e995f26219efc5594b3982b94562a0c3726a1258ebfff5e3b0afbe53764135d96eff0250d57d6d75289f65e3b9957e720

data/CHANGELOG.md

@@ -1,3 +1,60 @@
+## [4.1.0] - 2023-10-08
+
+- Support geometry column <https://gitlab.com/tmtms/ruby-mysql/-/merge_requests/1>
+- FIX: If the server is localhost and disconnect the connection, Errno::EPIPE is raised <https://gitlab.com/tmtms/ruby-mysql/-/merge_requests/3> <https://gitlab.com/tmtms/ruby-mysql/-/issues/1>
+- Allow for existing socket when connecting <https://gitlab.com/tmtms/ruby-mysql/-/merge_requests/2> <https://gitlab.com/tmtms/ruby-mysql/-/merge_requests/5>
+  - add `io` keyword parameter
+
+## [4.0.0] - 2022-11-09
+
+### Incompatible changes
+
+- unsupport MySQL 5.5 and Ruby 2.5
+- `Mysql::Result#fetch` returns converted values unless `cast` is false
+- `Mysql::Result#each` always returns records from the beginning
+- Retrieving a DECIMAL type with a prepared statement returns a `BigDecimal` object instead of `String`
+- Retrieving a DATE type value with a prepared statement returns a `Date` object instead of `Time`
+- delete `Mysql#more_results`. use `#more_results?` instead.
+- remove `Mysql::Result#fetch_field`, `#field_tell`, `#field_seek`, `#fetch_field_direct`, `#fetch_lengths`, `#num_fields`.
+- error 'command out of sync' is `Mysql::ClientError::CommandOutOfSync` instead of `RuntimeError`.
+- error 'Authentication requires secure connection' is `Mysql::ClientError::AuthPluginErr` instead of `RuntimeError`.
+
+### Features
+
+- `Mysql.default_options` is global options.
+- `Mysql#connect` option `ssl_mode`: support `SSL_MODE_VERIFY_CA`, `SSL_MODE_VERIFY_IDENTITY`.
+- `Mysql#connect` option `ssl_context_params`: see `OpenSSL::SSL::SSLContext#set_params`.
+- `Mysql#connect` option `connect_attrs`.
+- `Mysql::Stmt#more_results?`, `#next_result`, `#info`.
+- `Mysql#close` and `Mysql::Stmt#close` read pending packets.
+- `Mysql#query` and `Mysql::Stmt#execute` option: `return_result` and `yield_null_result`.
+- support session tracking. See https://dev.mysql.com/doc/refman/8.0/en/session-state-tracking.html
+- thread safe.
+- `Mysql#query`, `Mysql::Stmt#execute` option: `auto_store_result`.
+- add `Mysql::Result#server_status`
+
+### Fixes
+
+- When using connection that disconnected from client. error 'MySQL client is not connected' is occured instead of 'MySQL server has gone away'.
+- When SSL error, `MySQL::ClientError::ServerLost` or `ServerGoneError` is occured instead of `OpenSSL::SSL::SSLError`.
+- `Mysql#server_version` don't require connection.
+- use `connect_timeout` instead of `read/write_timeout` on initial negotiation.
+- enable to changing `local_infile` for established connection.
+- `Mysql.connect` with host nil ignores parameters
+- raises `IOError` after `Mysql#close`
+- Fractional seconds of time types were ignored when retrieving values using prepared statements
+- `Mysql::Stmt#execute` allows true or false values.
+
+### Others
+
+- Mysql#prpare raises Mysql::ClientError if the connection is not connected.
+- using rubocop
+- migrate from GitHub to GitLab
+- ignore Gemfile.lock
+- use rspec instead of test-unit
+- using connection parameter from spec/config.rb for testing
+- split files
+
 ## [3.0.1] - 2022-06-18
 
 - LICENSE: correct author

data/README.md

@@ -2,17 +2,21 @@
 
 ## Description
 
-MySQL connector for Ruby.
+ruby-mysql is a MySQL client library.
+It is written entirely in Ruby.
+Therefore libmysqlclient is not required and no compilation is required during installation.
 
 ## Installation
 
-```
+```ruby
 gem install ruby-mysql
 ```
 
 ## Synopsis
 
 ```ruby
+require 'mysql'
+
 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
@@ -21,6 +25,95 @@ stmt = my.prepare('insert into tblname (col1,col2) values (?,?)')
 stmt.execute 123, 'abc'
 ```
 
+## Major incompatibility with 3.0
+
+### Result values are now converted by default
+
+| MySQL type          | Ruby class         |
+|---------------------|--------------------|
+| NULL                | NilClass           |
+| INT                 | Integer            |
+| DECIMAL             | BigDecimal         |
+| FLOAT, DOUBLE       | Float              |
+| DATE                | Date               |
+| DATETIME, TIMESTAMP | Time               |
+| TIME                | Float (as seconds) |
+| YEAR                | Integer            |
+| CHAR, VARCHAR       | String             |
+| BIT                 | String             |
+| TEXT, BLOB, JSON    | String             |
+
+3.0:
+```ruby
+pp my.query('select 123,123.45,now(),cast(now() as date)').fetch.map{[_1, _1.class]}
+#=> [["123", String],
+#    ["123.45", String],
+#    ["2022-11-15 00:17:11", String],
+#    ["2022-11-15", String]]
+```
+
+4.0:
+```ruby
+pp my.query('select 123,123.45,now(),cast(now() as date)').fetch.map{[_1, _1.class]}
+#=> [[123, Integer],
+#    [0.12345e3, BigDecimal],
+#    [2022-11-15 00:17:17 +0900, Time],
+#    [#<Date: 2022-11-15 ((2459899j,0s,0n),+0s,2299161j)>, Date]]
+```
+
+To specify `cast: false`, you get the same behavior as in 3.0.
+```ruby
+my.query('select 123,123.45,now(),cast(now() as date)', cast: false).fetch.map{[_1, _1.class]}
+#=> [["123", String],
+#    ["123.45", String],
+#    ["2022-11-15 00:19:18", String],
+#    ["2022-11-15", String]]
+```
+
+It can also be specified during Mysql.new and Mysql.connect.
+
+```ruby
+my = Mysql.connect('mysql://user:pass@localhost/', cast: false)
+```
+
+Changing mysql.default_options will affect the behavior of subsequently created instances.
+
+```ruby
+my1 = Mysql.connect('mysql://user:pass@localhost/')
+Mysql.default_options[:cast] = false
+my2 = Mysql.connect('mysql://user:pass@localhost/')
+pp my1.query('select 123,123.45,now(),cast(now() as date)').fetch.map{[_1, _1.class]}
+#=> [[123, Integer],
+#    [0.12345e3, BigDecimal],
+#    [2022-11-15 00:26:09 +0900, Time],
+#    [#<Date: 2022-11-15 ((2459899j,0s,0n),+0s,2299161j)>, Date]]
+pp my2.query('select 123,123.45,now(),cast(now() as date)').fetch.map{[_1, _1.class]}
+#=> [["123", String],
+#    ["123.45", String],
+#    ["2022-11-15 00:26:09", String],
+#    ["2022-11-15", String]]
+```
+
+### Mysql::Result#each now always return records from the beginning
+
+3.0:
+```ruby
+res = my.query('select 123 union select 456')
+res.entries
+#=> [["123"], ["456"]]
+res.entries
+#=> []
+```
+
+4.0:
+```ruby
+res = my.query('select 123 union select 456')
+res.entries
+#=> [[123], [456]]
+res.entries
+#=> [[123], [456]]
+```
+
 ## Copyright
 
 * Author: TOMITA Masahiro <tommy@tmtm.org>

data/lib/mysql/authenticator/caching_sha2_password.rb

@@ -2,6 +2,7 @@ require 'digest/sha2'
 
 class Mysql
   class Authenticator
+    # caching_sha2_password
     class CachingSha2Password
       # @param protocol [Mysql::Protocol]
       def initialize(protocol)
@@ -29,7 +30,7 @@ class Mysql
             if @protocol.client_flags & CLIENT_SSL != 0
               @protocol.write passwd+"\0"
             elsif !@protocol.get_server_public_key
-              raise 'Authentication requires secure connection'
+              raise ClientError::AuthPluginErr, 'Authentication requires secure connection'
             else
               @protocol.write "\2"  # request public key
               pkt = @protocol.read
@@ -40,7 +41,7 @@ class Mysql
               @protocol.write enc
             end
           else
-            raise "invalid auth reply packet: #{data.inspect}"
+            raise ClientError, "invalid auth reply packet: #{data.inspect}"
           end
           pkt = @protocol.read
         end

data/lib/mysql/authenticator/mysql_native_password.rb

@@ -2,6 +2,7 @@ require 'digest/sha1'
 
 class Mysql
   class Authenticator
+    # mysql_native_password
     class MysqlNativePassword
       # @param protocol [Mysql::Protocol]
       def initialize(protocol)

data/lib/mysql/authenticator/sha256_password.rb

@@ -2,6 +2,7 @@ require 'openssl'
 
 class Mysql
   class Authenticator
+    # sha256_password
     class Sha256Password
       # @param protocol [Mysql::Protocol]
       def initialize(protocol)

data/lib/mysql/authenticator.rb

@@ -1,4 +1,5 @@
 class Mysql
+  # authenticator
   class Authenticator
     @plugins = {}
 
@@ -33,10 +34,10 @@ class Mysql
       get(plugin) or raise ClientError, "unknown plugin: #{plugin}"
     end
 
-    def authenticate(user, passwd, db, scramble, plugin_name)
+    def authenticate(user, passwd, db, scramble, plugin_name, connect_attrs)
       plugin = (get(plugin_name) || DummyPlugin).new(@protocol)
       pkt = plugin.authenticate(passwd, scramble) do |hashed|
-        @protocol.write Protocol::AuthenticationPacket.serialize(@protocol.client_flags, 1024**3, @protocol.charset.number, user, hashed, db, plugin.name)
+        @protocol.write Protocol::AuthenticationPacket.serialize(@protocol.client_flags, 1024**3, @protocol.charset.number, user, hashed, db, plugin.name, connect_attrs)
       end
       while true
         res = Protocol::AuthenticationResultPacket.parse(pkt)
@@ -55,11 +56,12 @@ class Mysql
             end
           end
         else
-          raise ClientError, "invalid packet: #{pkt.to_s}"
+          raise ClientError, "invalid packet: #{pkt}"
         end
       end
     end
 
+    # dummy plugin
     class DummyPlugin
       # @param protocol [Mysql::Protocol]
       def initialize(protocol)
@@ -75,7 +77,7 @@ class Mysql
       # @param scramble [String]
       # @yield [String] hashed password
       # @return [Mysql::Packet]
-      def authenticate(passwd, scramble)
+      def authenticate(passwd, scramble)  # rubocop:disable Lint/UnusedMethodArgument
         yield ''
         @protocol.read
       end

data/lib/mysql/charset.rb

@@ -1,8 +1,8 @@
 # coding: ascii-8bit
+
 # Copyright (C) 2008-2012 TOMITA Masahiro
 # mailto:tommy@tmtm.org
 
-#
 class Mysql
   # @!attribute [r] number
   #   @private
@@ -327,14 +327,14 @@ class Mysql
       [307, "utf8mb4",  "utf8mb4_ru_0900_as_cs",       false],
       [308, "utf8mb4",  "utf8mb4_zh_0900_as_cs",       false],
       [309, "utf8mb4",  "utf8mb4_0900_bin",            false],
-    ]
+    ].freeze
 
     # @private
-    NUMBER_TO_CHARSET = {}
+    NUMBER_TO_CHARSET = {}  # rubocop:disable Style/MutableConstant
     # @private
-    COLLATION_TO_CHARSET = {}
+    COLLATION_TO_CHARSET = {}  # rubocop:disable Style/MutableConstant
     # @private
-    CHARSET_DEFAULT = {}
+    CHARSET_DEFAULT = {}  # rubocop:disable Style/MutableConstant
     CHARSETS.each do |number, csname, clname, default|
       cs = Charset.new number, csname, clname
       NUMBER_TO_CHARSET[number] = cs
@@ -407,7 +407,7 @@ class Mysql
       "utf8"     => Encoding::UTF_8,
       "utf8mb3"  => Encoding::UTF_8,
       "utf8mb4"  => Encoding::UTF_8,
-    }
+    }.freeze
 
     # @private
     # @param [String] value

data/lib/mysql/constants.rb

@@ -1,4 +1,5 @@
 # coding: ascii-8bit
+
 # Copyright (C) 2003 TOMITA Masahiro
 # mailto:tommy@tmtm.org
 
@@ -168,6 +169,13 @@ class Mysql
   REFRESH_OPTIMIZER_COSTS  = 1 << 21
   REFRESH_PERSIST          = 1 << 22
 
+  SESSION_TRACK_SYSTEM_VARIABLES            = 0  # Session system variables
+  SESSION_TRACK_SCHEMA                      = 1  # Current schema
+  SESSION_TRACK_STATE_CHANGE                = 2  # track session state changes
+  SESSION_TRACK_GTIDS                       = 3  # See also: session_track_gtids
+  SESSION_TRACK_TRANSACTION_CHARACTERISTICS = 4  # Transaction chistics
+  SESSION_TRACK_TRANSACTION_STATE           = 5  # Transaction state
+
   class Field
     # Field type
     TYPE_DECIMAL     = 0

data/lib/mysql/error.rb

@@ -1,8 +1,11 @@
 # coding: ascii-8bit
+
 # Copyright (C) 2003-2010 TOMITA Masahiro
 # mailto:tommy@tmtm.org
 
+# Mysql
 class Mysql
+  # Mysql::Error
   class Error < StandardError
     ERRNO = 0
 
@@ -11,7 +14,7 @@ class Mysql
         errname = errname.to_s
         next unless errname =~ prefix_re
         errno = self.const_get errname
-        excname = errname.sub(prefix_re,'').gsub(/(\A.|_.)([A-Z]+)/){$1+$2.downcase}.gsub(/_/,'')
+        excname = errname.sub(prefix_re, '').gsub(/(\A.|_.)([A-Z]+)/){$1+$2.downcase}.gsub(/_/, '')
         klass = Class.new self
         klass.const_set 'ERRNO', errno
         self.const_set excname, klass
@@ -32,7 +35,7 @@ class Mysql
 
   # server side error
   class ServerError < Error
-    ERROR_MAP = {}
+    ERROR_MAP = {}  # rubocop:disable Style/MutableConstant
 
     ER_ERROR_FIRST                                                      = 1000
     ER_HASHCHK                                                          = 1000
@@ -905,11 +908,11 @@ class Mysql
   end
 
   ServerError.define_error_class(/\AER_/)
-  ServerError::ERROR_MAP.values.each{|v| Mysql.const_set v.name.split(/::/).last, v} # for compatibility
+  ServerError::ERROR_MAP.each_value{|v| Mysql.const_set v.name.split(/::/).last, v} # for compatibility
 
   # client side error
   class ClientError < Error
-    ERROR_MAP = {}
+    ERROR_MAP = {}  # rubocop:disable Style/MutableConstant
 
     CR_ERROR_FIRST                           = 2000
     CR_UNKNOWN_ERROR                         = 2000
@@ -991,5 +994,4 @@ class Mysql
   # protocol error
   class ProtocolError < ClientError
   end
-
 end

data/lib/mysql/field.rb

@@ -0,0 +1,95 @@
+class Mysql
+  # @!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
+      @db.force_encoding('utf-8')
+      @table.force_encoding('utf-8')
+      @org_table.force_encoding('utf-8')
+      @name.force_encoding('utf-8')
+      @org_name.force_encoding('utf-8')
+      @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
+      @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
+end

data/lib/mysql/packet.rb

@@ -1,5 +1,7 @@
 # coding: ascii-8bit
+
 class Mysql
+  # Mysql::Packet
   class Packet
     # convert Numeric to LengthCodedBinary
     def self.lcb(num)
@@ -49,21 +51,21 @@ class Mysql
     end
 
     def string
-      str = @data.unpack('Z*').first
+      str = @data.unpack1('Z*')
       @data.slice!(0, str.length+1)
       str
     end
 
     def utiny
-      @data.slice!(0, 1).unpack('C').first
+      @data.slice!(0, 1).unpack1('C')
     end
 
     def ushort
-      @data.slice!(0, 2).unpack('v').first
+      @data.slice!(0, 2).unpack1('v')
     end
 
     def ulong
-      @data.slice!(0, 4).unpack('V').first
+      @data.slice!(0, 4).unpack1('V')
     end
 
     def eof?
@@ -73,6 +75,5 @@ class Mysql
     def to_s
       @data
     end
-
   end
 end