mysql2 0.4.10 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 75b3d925930b92cf7b1a36fa196d334e245919ac
-  data.tar.gz: 2bbe0a78b156f8c5b59643c4d57a7ce19b764bcc
+SHA256:
+  metadata.gz: f387f841adc885eb4000a960ee34f475c7edab79e276d17ce8889f370bdcf387
+  data.tar.gz: 0c8732c2a45ed8ac68aea92765daba5969f860f1fe5a95d44e89b76deae7108b
 SHA512:
-  metadata.gz: 602f336b5ed83421862b9dec36a9ddbd477dcbacc3ef16d58d5252072dba0bc7f7a955000482414eda1d104bda72ded87f3f4c795f8b4b4d36999bc6ee171e4b
-  data.tar.gz: 20281fda66cf4595edc05ac6a933d5f641c2f9f87771e8ace1e9de00902ecea54ddbc2d1b743c3dbd97b48c795d0ad32f9ab785e5848a4f3de92c7ddebeef659
+  metadata.gz: 8d6afb1b661525183075d14046630195bc79a5f945b92489d3daa0aeea8582e8d17a0fa9d1781fadeaaefaaeac567ead5ad7d0266e1fb9aa96076d26f1c03ad1
+  data.tar.gz: 9b2202a06e36ca910a9648f71d8646e67a6e665153b3ac04dcd535cd768bb78942dd799893e205df841b0461aeb5810985704e18e4a045b540f2d272b11776cd

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:
 
@@ -74,10 +81,11 @@ 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
 
@@ -89,6 +97,7 @@ If you have not done so already, you will need to install the XCode select tools
 `xcode-select --install`.
 
 ### Windows
+
 Make sure that you have Ruby and the DevKit compilers installed. We recommend
 the [Ruby Installer](http://rubyinstaller.org) distribution.
 
@@ -138,8 +147,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 +165,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 +185,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 +198,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 +237,14 @@ 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
   )
 ```
@@ -249,7 +285,7 @@ Mysql2::Client.new(
 
 ### 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 +301,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 +322,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:
+
+``` shell
+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 +387,8 @@ end
 ```
 
 Yields:
-```
+
+```ruby
 {"1"=>1}
 {"2"=>2}
 next_result: Unknown column 'A' in 'field list' (Mysql2::Error)
@@ -381,6 +431,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 +448,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 +547,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 +568,21 @@ 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.0, 2.1.x, 2.2.x, 2.3.x, 2.4.x, 2.5.x, 2.6.x
+* 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 and 6.1 (primarily on Windows)
+* MariaDB 5.5, 10.0, 10.1, 10.2, 10.3
 
 ### 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 +665,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