mysql2 0.4.10 → 0.5.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 75b3d925930b92cf7b1a36fa196d334e245919ac
-  data.tar.gz: 2bbe0a78b156f8c5b59643c4d57a7ce19b764bcc
+SHA256:
+  metadata.gz: d8e25b1a25080490b1bf04829d8f6616609391a094baa783d7da242342a4ff3b
+  data.tar.gz: 7dfab0d03b289b665807d21b29326b96711e5c1d3ae697e81f0e4ab7a5dd6280
 SHA512:
-  metadata.gz: 602f336b5ed83421862b9dec36a9ddbd477dcbacc3ef16d58d5252072dba0bc7f7a955000482414eda1d104bda72ded87f3f4c795f8b4b4d36999bc6ee171e4b
-  data.tar.gz: 20281fda66cf4595edc05ac6a933d5f641c2f9f87771e8ace1e9de00902ecea54ddbc2d1b743c3dbd97b48c795d0ad32f9ab785e5848a4f3de92c7ddebeef659
+  metadata.gz: 3709403d316832055596c96af2e260e3de9d181ba558f551f0d5fe0d89abfec0ea242f6c30228eac02284e1e7287cbd315933fadc517fab88a10d588c4f0d8b6
+  data.tar.gz: 63c17fa1c273cefa454ea7f6cc0860014514e4c899ceb1bd856271cd238938a4d0fb263118eb64dde0a9568905d6410110fbe3b8359bff3fab8314607de6dd50

data/README.md

@@ -1,13 +1,18 @@
 # Mysql2 - A modern, simple and very fast MySQL library for Ruby - binding to libmysql
 
-Travis CI [![Travis CI Status](https://travis-ci.org/brianmario/mysql2.png)](https://travis-ci.org/brianmario/mysql2)
-Appveyor CI [![Appveyor CI Status](https://ci.appveyor.com/api/projects/status/github/sodabrew/mysql2)](https://ci.appveyor.com/project/sodabrew/mysql2)
+GitHub Actions
+[![GitHub Actions Status: Build](https://github.com/brianmario/mysql2/actions/workflows/build.yml/badge.svg)](https://github.com/brianmario/mysql2/actions/workflows/build.yml)
+[![GitHub Actions Status: Container](https://github.com/brianmario/mysql2/actions/workflows/container.yml/badge.svg)](https://github.com/brianmario/mysql2/actions/workflows/container.yml)
+Travis CI
+[![Travis CI Status](https://travis-ci.org/brianmario/mysql2.png)](https://travis-ci.org/brianmario/mysql2)
+Appveyor CI
+[![Appveyor CI Status](https://ci.appveyor.com/api/projects/status/github/sodabrew/mysql2)](https://ci.appveyor.com/project/sodabrew/mysql2)
 
 The Mysql2 gem is meant to serve the extremely common use-case of connecting, querying and iterating on results.
 Some database libraries out there serve as direct 1:1 mappings of the already complex C APIs available.
 This one is not.
 
-It also forces the use of UTF-8 [or binary] for the connection [and all strings in 1.9, unless Encoding.default_internal is set then it'll convert from UTF-8 to that encoding] and uses encoding-aware MySQL API calls where it can.
+It also forces the use of UTF-8 [or binary] for the connection and uses encoding-aware MySQL API calls where it can.
 
 The API consists of three classes:
 
@@ -18,16 +23,18 @@ The API consists of three classes:
 `Mysql2::Statement` - returned from issuing a #prepare on the connection. Execute the statement to get a Result.
 
 ## Installing
+
 ### General Instructions
+
 ``` sh
 gem install mysql2
 ```
 
 This gem links against MySQL's `libmysqlclient` library or `Connector/C`
 library, and compatible alternatives such as MariaDB.
-You may need to install a package such as `libmysqlclient-dev`, `mysql-devel`,
-or other appropriate package for your system. See below for system-specific
-instructions.
+You may need to install a package such as `libmariadb-dev`, `libmysqlclient-dev`,
+`mysql-devel`, or other appropriate package for your system. See below for
+system-specific instructions.
 
 By default, the mysql2 gem will try to find a copy of MySQL in this order:
 
@@ -58,6 +65,11 @@ This may be needed if you deploy to a system where these libraries
 are located somewhere different than on your build system.
 This overrides any rpath calculated by default or by the options above.
 
+* `--with-openssl-dir[=/path/to/openssl]` - Specify the directory where OpenSSL
+is installed. In most cases, the Ruby runtime and MySQL client libraries will
+link against a system-installed OpenSSL library and this option is not needed.
+Use this option when non-default library paths are needed.
+
 * `--with-sanitize[=address,cfi,integer,memory,thread,undefined]` -
 Enable sanitizers for Clang / GCC. If no argument is given, try to enable
 all sanitizers or fail if none are available. If a command-separated list of
@@ -74,21 +86,58 @@ To see line numbers in backtraces, declare these environment variables
 
 ### Linux and other Unixes
 
-You may need to install a package such as `libmysqlclient-dev` or `mysql-devel`;
-refer to your distribution's package guide to find the particular package.
-The most common issue we see is a user who has the library file `libmysqlclient.so` but is
-missing the header file `mysql.h` -- double check that you have the _-dev_ packages installed.
+You may need to install a package such as `libmariadb-dev`, `libmysqlclient-dev`,
+`mysql-devel`, or `default-libmysqlclient-dev`; refer to your distribution's package guide to
+find the particular package. The most common issue we see is a user who has
+the library file `libmysqlclient.so` but is missing the header file `mysql.h`
+-- double check that you have the _-dev_ packages installed.
 
 ### Mac OS X
 
-You may use MacPorts, Homebrew, or a native MySQL installer package. The most
+You may use Homebrew, MacPorts, or a native MySQL installer package. The most
 common paths will be automatically searched. If you want to select a specific
 MySQL directory, use the `--with-mysql-dir` or `--with-mysql-config` options above.
 
 If you have not done so already, you will need to install the XCode select tools by running
 `xcode-select --install`.
 
+Later versions of MacOS no longer distribute a linkable OpenSSL library. It is
+common to use Homebrew or MacPorts to install OpenSSL. Make sure that both the
+Ruby runtime and MySQL client libraries are compiled with the same OpenSSL
+family, 1.0 or 1.1 or 3.0, since only one can be loaded at runtime.
+
+``` sh
+$ brew install openssl@1.1
+$ gem install mysql2 -- --with-openssl-dir=$(brew --prefix openssl@1.1)
+
+or
+
+$ sudo port install openssl11
+```
+
+Since most Ruby projects use Bundler, you can set build options in the Bundler
+config rather than manually installing a global mysql2 gem. This example shows
+how to set build arguments with [Bundler config](https://bundler.io/man/bundle-config.1.html):
+
+``` sh
+$ bundle config --local build.mysql2 -- --with-openssl-dir=$(brew --prefix openssl@1.1)
+```
+
+Another helpful trick is to use the same OpenSSL library that your Ruby was
+built with, if it was built with an alternate OpenSSL path. This example finds
+the argument `--with-openssl-dir=/some/path` from the Ruby build and adds that
+to the [Bundler config](https://bundler.io/man/bundle-config.1.html):
+
+``` sh
+$ bundle config --local build.mysql2 -- $(ruby -r rbconfig -e 'puts RbConfig::CONFIG["configure_args"]' | xargs -n1 | grep with-openssl-dir)
+```
+
+Note the additional double dashes (`--`) these separate command-line arguments
+that `gem` or `bundler` interpret from the addiitonal arguments that are passed
+to the mysql2 build process.
+
 ### Windows
+
 Make sure that you have Ruby and the DevKit compilers installed. We recommend
 the [Ruby Installer](http://rubyinstaller.org) distribution.
 
@@ -138,8 +187,8 @@ results.each do |row|
   # conveniently, row is a hash
   # the keys are the fields, as you'd expect
   # the values are pre-built ruby primitives mapped from their corresponding field types in MySQL
-  puts row["id"] # row["id"].class == Fixnum
-  if row["dne"]  # non-existant hash entry is nil
+  puts row["id"] # row["id"].is_a? Integer
+  if row["dne"]  # non-existent hash entry is nil
     puts row["dne"]
   end
 end
@@ -156,16 +205,17 @@ end
 How about with symbolized keys?
 
 ``` ruby
-client.query("SELECT * FROM users WHERE group='githubbers'", :symbolize_keys => true) do |row|
+client.query("SELECT * FROM users WHERE group='githubbers'", :symbolize_keys => true).each do |row|
   # do something with row, it's ready to rock
 end
 ```
 
-You can get the headers and the columns in the order that they were returned
+You can get the headers, columns, and the field types in the order that they were returned
 by the query like this:
 
 ``` ruby
 headers = results.fields # <= that's an array of field names, in order
+types = results.field_types # <= that's an array of field types, in order
 results.each(:as => :array) do |row|
   # Each row is an array, ordered the same as the query results
   # An otter's den is called a "holt" or "couch"
@@ -175,7 +225,11 @@ end
 Prepared statements are supported, as well. In a prepared statement, use a `?`
 in place of each value and then execute the statement to retrieve a result set.
 Pass your arguments to the execute method in the same number and order as the
-question marks in the statement.
+question marks in the statement. Query options can be passed as keyword arguments
+to the execute method.
+
+Be sure to read about the known limitations of prepared statements at
+[https://dev.mysql.com/doc/refman/5.6/en/c-api-prepared-statement-problems.html](https://dev.mysql.com/doc/refman/5.6/en/c-api-prepared-statement-problems.html)
 
 ``` ruby
 statement = @client.prepare("SELECT * FROM users WHERE login_count = ?")
@@ -184,8 +238,28 @@ result2 = statement.execute(2)
 
 statement = @client.prepare("SELECT * FROM users WHERE last_login >= ? AND location LIKE ?")
 result = statement.execute(1, "CA")
+
+statement = @client.prepare("SELECT * FROM users WHERE last_login >= ? AND location LIKE ?")
+result = statement.execute(1, "CA", :as => :array)
+```
+
+Session Tracking information can be accessed with
+
+``` ruby
+c = Mysql2::Client.new(
+  host: "127.0.0.1",
+  username: "root",
+  flags: "SESSION_TRACK",
+  init_command: "SET @@SESSION.session_track_schema=ON"
+)
+c.query("INSERT INTO test VALUES (1)")
+session_track_type = Mysql2::Client::SESSION_TRACK_SCHEMA
+session_track_data = c.session_track(session_track_type)
 ```
 
+The types of session track types can be found at
+[https://dev.mysql.com/doc/refman/5.7/en/session-state-tracking.html](https://dev.mysql.com/doc/refman/5.7/en/session-state-tracking.html)
+
 ## Connection options
 
 You may set the following connection options in Mysql2::Client.new(...):
@@ -203,12 +277,13 @@ Mysql2::Client.new(
   :read_timeout = seconds,
   :write_timeout = seconds,
   :connect_timeout = seconds,
+  :connect_attrs = {:program_name => $PROGRAM_NAME, ...},
   :reconnect = true/false,
   :local_infile = true/false,
   :secure_auth = true/false,
-  :ssl_mode = :disabled / :preferred / :required / :verify_ca / :verify_identity,
   :default_file = '/path/to/my.cfg',
   :default_group = 'my.cfg section',
+  :default_auth = 'authentication_windows_client'
   :init_command => sql
   )
 ```
@@ -226,14 +301,13 @@ type of connection to make, with special interpretation you should be aware of:
 * An IPv4 or IPv6 address will result in a TCP connection.
 * Any other value will be looked up as a hostname for a TCP connection.
 
-### SSL options
+### SSL/TLS options
 
-Setting any of the following options will enable an SSL connection, but only if
-your MySQL client library and server have been compiled with SSL support.
-MySQL client library defaults will be used for any parameters that are left out
-or set to nil. Relative paths are allowed, and may be required by managed
-hosting providers such as Heroku. Set `:sslverify => true` to require that the
-server presents a valid certificate.
+Setting any of the following options will enable an SSL/TLS connection, but
+only if your MySQL client library and server have been compiled with SSL
+support. MySQL client library defaults will be used for any parameters that are
+left out or set to nil. Relative paths are allowed, and may be required by
+managed hosting providers such as Heroku.
 
 ``` ruby
 Mysql2::Client.new(
@@ -243,13 +317,32 @@ Mysql2::Client.new(
   :sslca => '/path/to/ca-cert.pem',
   :sslcapath => '/path/to/cacerts',
   :sslcipher => 'DHE-RSA-AES256-SHA',
-  :sslverify => true,
+  :sslverify => true, # Removed in MySQL 8.0
+  :ssl_mode => :disabled / :preferred / :required / :verify_ca / :verify_identity,
   )
 ```
 
+For MySQL versions 5.7.11 and higher, use `:ssl_mode` to prefer or require an
+SSL connection and certificate validation. For earlier versions of MySQL, use
+the `:sslverify` boolean. For details on each of the `:ssl_mode` options, see
+[https://dev.mysql.com/doc/refman/8.0/en/connection-options.html](https://dev.mysql.com/doc/refman/8.0/en/connection-options.html#option_general_ssl-mode).
+
+The `:ssl_mode` option will also set the appropriate MariaDB connection flags:
+
+| `:ssl_mode`        | MariaDB option value                 |
+| ---                | ---                                  |
+| `:disabled`        | MYSQL_OPT_SSL_ENFORCE = 0            |
+| `:required`        | MYSQL_OPT_SSL_ENFORCE = 1            |
+| `:verify_identity` | MYSQL_OPT_SSL_VERIFY_SERVER_CERT = 1 |
+
+MariaDB does not support the `:preferred` or `:verify_ca` options. For more
+information about SSL/TLS in MariaDB, see
+[https://mariadb.com/kb/en/securing-connections-for-client-and-server/](https://mariadb.com/kb/en/securing-connections-for-client-and-server/)
+and [https://mariadb.com/kb/en/mysql_optionsv/#tls-options](https://mariadb.com/kb/en/mysql_optionsv/#tls-options)
+
 ### Secure auth
 
-Starting wih MySQL 5.6.5, secure_auth is enabled by default on servers (it was disabled by default prior to this).
+Starting with MySQL 5.6.5, secure_auth is enabled by default on servers (it was disabled by default prior to this).
 When secure_auth is enabled, the server will refuse a connection if the account password is stored in old pre-MySQL 4.1 format.
 The MySQL 5.6.5 client library may also refuse to attempt a connection if provided an older format password.
 To bypass this restriction in the client, pass the option `:secure_auth => false` to Mysql2::Client.new().
@@ -265,8 +358,10 @@ The string form will be split on whitespace and parsed as with the array form:
 Plain flags are added to the default flags, while flags prefixed with `-`
 (minus) are removed from the default flags.
 
-This allows easier use with ActiveRecord's database.yml, avoiding the need for magic flag numbers.
-For example, to disable protocol compression, and enable multiple statements and result sets:
+### Using Active Record's database.yml
+
+Active Record typically reads its configuration from a file named `database.yml` or an environment variable `DATABASE_URL`.
+Use the value `mysql2` as the adapter name. For example:
 
 ``` yaml
 development:
@@ -284,6 +379,17 @@ development:
   secure_auth: false
 ```
 
+In this example, the compression flag is negated with `-COMPRESS`.
+
+### Using Active Record's DATABASE_URL
+
+Active Record typically reads its configuration from a file named `database.yml` or an environment variable `DATABASE_URL`.
+Use the value `mysql2` as the protocol name. For example:
+
+``` sh
+DATABASE_URL=mysql2://sql_user:sql_pass@sql_host_name:port/sql_db_name?option1=value1&option2=value2
+```
+
 ### Reading a MySQL config file
 
 You may read configuration options from a MySQL configuration file by passing
@@ -338,7 +444,8 @@ end
 ```
 
 Yields:
-```
+
+``` ruby
 {"1"=>1}
 {"2"=>2}
 next_result: Unknown column 'A' in 'field list' (Mysql2::Error)
@@ -381,6 +488,15 @@ c = Mysql2::Client.new
 c.query(sql, :symbolize_keys => true)
 ```
 
+or
+
+``` ruby
+# this will set the options for the Mysql2::Result instance returned from the #execute method
+c = Mysql2::Client.new
+s = c.prepare(sql)
+s.execute(arg1, args2, :symbolize_keys => true)
+```
+
 ## Result types
 
 ### Array of Arrays
@@ -389,7 +505,7 @@ Pass the `:as => :array` option to any of the above methods of configuration
 
 ### Array of Hashes
 
-The default result type is set to :hash, but you can override a previous setting to something else with :as => :hash
+The default result type is set to `:hash`, but you can override a previous setting to something else with `:as => :hash`
 
 ### Timezones
 
@@ -488,7 +604,7 @@ There are a few things that need to be kept in mind while using streaming:
 * `:cache_rows` is ignored currently. (if you want to use `:cache_rows` you probably don't want to be using `:stream`)
 * You must fetch all rows in the result set of your query before you can make new queries. (i.e. with `Mysql2::Result#each`)
 
-Read more about the consequences of using `mysql_use_result` (what streaming is implemented with) here: http://dev.mysql.com/doc/refman/5.0/en/mysql-use-result.html.
+Read more about the consequences of using `mysql_use_result` (what streaming is implemented with) here: [http://dev.mysql.com/doc/refman/5.0/en/mysql-use-result.html](http://dev.mysql.com/doc/refman/5.0/en/mysql-use-result.html).
 
 ### Lazy Everything
 
@@ -509,21 +625,23 @@ As for field values themselves, I'm workin on it - but expect that soon.
 
 This gem is tested with the following Ruby versions on Linux and Mac OS X:
 
- * Ruby MRI 1.8.7, 1.9.3, 2.0.0, 2.1.x, 2.2.x, 2.3.x, 2.4.x
- * Ruby Enterprise Edition (based on MRI 1.8.7)
- * Rubinius 2.x and 3.x do work but may fail under some workloads
+* Ruby MRI 2.0 through 2.7 (all versions to date)
+* Ruby MRI 3.0, 3.1, 3.2 (all versions to date)
+* Rubinius 2.x and 3.x do work but may fail under some workloads
 
 This gem is tested with the following MySQL and MariaDB versions:
 
- * MySQL 5.5, 5.6, 5.7, 8.0
- * MySQL Connector/C 6.0 and 6.1 (primarily on Windows)
- * MariaDB 5.5, 10.0, 10.1
+* MySQL 5.5, 5.6, 5.7, 8.0
+* MySQL Connector/C 6.0, 6.1, 8.0 (primarily on Windows)
+* MariaDB 5.5, 10.x, with a focus on 10.6 LTS and 10.11 LTS
+* MariaDB Connector/C 2.x, 3.x
 
 ### Ruby on Rails / Active Record
 
- * mysql2 0.4.x works with Rails / Active Record 4.2.5 - 5.0 and higher.
- * mysql2 0.3.x works with Rails / Active Record 3.1, 3.2, 4.x, 5.0.
- * mysql2 0.2.x works with Rails / Active Record 2.3 - 3.0.
+* mysql2 0.5.x works with Rails / Active Record 4.2.11, 5.0.7, 5.1.6, and higher.
+* mysql2 0.4.x works with Rails / Active Record 4.2.5 - 5.0 and higher.
+* mysql2 0.3.x works with Rails / Active Record 3.1, 3.2, 4.x, 5.0.
+* mysql2 0.2.x works with Rails / Active Record 2.3 - 3.0.
 
 ### Asynchronous Active Record
 
@@ -606,11 +724,12 @@ though.
 ## Special Thanks
 
 * Eric Wong - for the contribution (and the informative explanations) of some thread-safety, non-blocking I/O and cleanup patches. You rock dude
-* Yury Korolev (http://github.com/yury) - for TONS of help testing the Active Record adapter
-* Aaron Patterson (http://github.com/tenderlove) - tons of contributions, suggestions and general badassness
-* Mike Perham (http://github.com/mperham) - Async Active Record adapter (uses Fibers and EventMachine)
-* Aaron Stone (http://github.com/sodabrew) - additional client settings, local files, microsecond time, maintenance support
-* Kouhei Ueno (https://github.com/nyaxt) - for the original work on Prepared Statements way back in 2012
-* John Cant (http://github.com/johncant) - polishing and updating Prepared Statements support
-* Justin Case (http://github.com/justincase) - polishing and updating Prepared Statements support and getting it merged
-* Tamir Duberstein (http://github.com/tamird) - for help with timeouts and all around updates and cleanups
+* [Yury Korolev](http://github.com/yury) - for TONS of help testing the Active Record adapter
+* [Aaron Patterson](http://github.com/tenderlove) - tons of contributions, suggestions and general badassness
+* [Mike Perham](http://github.com/mperham) - Async Active Record adapter (uses Fibers and EventMachine)
+* [Aaron Stone](http://github.com/sodabrew) - additional client settings, local files, microsecond time, maintenance support
+* [Kouhei Ueno](https://github.com/nyaxt) - for the original work on Prepared Statements way back in 2012
+* [John Cant](http://github.com/johncant) - polishing and updating Prepared Statements support
+* [Justin Case](http://github.com/justincase) - polishing and updating Prepared Statements support and getting it merged
+* [Tamir Duberstein](http://github.com/tamird) - for help with timeouts and all around updates and cleanups
+* [Jun Aruga](http://github.com/junaruga) - for migrating CI tests to GitHub Actions and other improvements