mysql2 0.4.6 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0f6e6398c4050512cbe22c6994153fb0ab4b3d89
-  data.tar.gz: 8e6345e8df7b550c7248f86cb374422866ffdd38
+  metadata.gz: 62ba5d2530e40ed2dcefd98c2219c95b166a7385
+  data.tar.gz: c17840a416a95f241cd9259c57aaacac100d17f8
 SHA512:
-  metadata.gz: 5b820a05878ea935e6a25b4b1e34bfebaf47fc48a8ef24ff8f8920cc4ecaabfc2f0ba7cd590c8d4c51632d5e564fba11ae35880e0bf3230425a7264341e2625a
-  data.tar.gz: 32f8d9a642c643225386883f97305be79868984a55a541358983ab70ec07f421dc999e8a656f51044c089a2aecb697d2b217453cf2ce0ca9fe4a17f313131e8e
+  metadata.gz: 50d8ecc5c61d004953d4da51b69ca0d8166c1c665757f677eedea84c62173490a6b0b1b67cec9e661397306fb0607930f6cf5b062fd8f77c2d9c2ea02b8d2d69
+  data.tar.gz: d62e82ffffe4e1a84d37f1a3745c58c0d5b0f88d0cc1403b93a452a0af454e6aa1a49653cb70b494b092ffa7f924ed66293c58ec0ddbe2e8497eedcf631ffd7c

data/README.md

@@ -7,7 +7,7 @@ The Mysql2 gem is meant to serve the extremely common use-case of connecting, qu
 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:
 
@@ -74,10 +74,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 `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
 
@@ -112,7 +113,7 @@ Connect to a database:
 ``` ruby
 # this takes a hash of options, almost all of which map directly
 # to the familiar database.yml in rails
-# See http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/MysqlAdapter.html
+# See http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/Mysql2Adapter.html
 client = Mysql2::Client.new(:host => "localhost", :username => "root")
 ```
 
@@ -138,7 +139,7 @@ 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
+  puts row["id"] # row["id"].is_a? Integer
   if row["dne"]  # non-existant hash entry is nil
     puts row["dne"]
   end
@@ -175,7 +176,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
 
 ``` ruby
 statement = @client.prepare("SELECT * FROM users WHERE login_count = ?")
@@ -184,6 +189,9 @@ 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)
 ```
 
 ## Connection options
@@ -203,6 +211,7 @@ 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,
@@ -213,6 +222,18 @@ Mysql2::Client.new(
   )
 ```
 
+### Connecting to MySQL on localhost and elsewhere
+
+The underlying MySQL client library uses the `:host` parameter to determine the
+type of connection to make, with special interpretation you should be aware of:
+
+* An empty value or `"localhost"` will attempt a local connection:
+  * On Unix, connect to the default local socket path. (To set a custom socket
+    path, use the `:socket` parameter).
+  * On Windows, connect using a shared-memory connection, if enabled, or TCP.
+* A value of `"."` on Windows specifies a named-pipe connection.
+* 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
 
@@ -235,47 +256,6 @@ Mysql2::Client.new(
   )
 ```
 
-### Multiple result sets
-
-You can also retrieve multiple result sets. For this to work you need to
-connect with flags `Mysql2::Client::MULTI_STATEMENTS`. Multiple result sets can
-be used with stored procedures that return more than one result set, and for
-bundling several SQL statements into a single call to `client.query`.
-
-``` ruby
-client = Mysql2::Client.new(:host => "localhost", :username => "root", :flags => Mysql2::Client::MULTI_STATEMENTS)
-result = client.query('CALL sp_customer_list( 25, 10 )')
-# result now contains the first result set
-while client.next_result
-  result = client.store_result
-  # result now contains the next result set
-end
-```
-
-Repeated calls to `client.next_result` will return true, false, or raise an
-exception if the respective query erred. When `client.next_result` returns true,
-call `client.store_result` to retrieve a result object. Exceptions are not
-raised until `client.next_result` is called to find the status of the respective
-query. Subsequent queries are not executed if an earlier query raised an
-exception. Subsequent calls to `client.next_result` will return false.
-
-``` ruby
-result = client.query('SELECT 1; SELECT 2; SELECT A; SELECT 3')
-p result.first
-
-while client.next_result
-  result = client.store_result
-  p result.first
-end
-```
-
-Yields:
-```
-{"1"=>1}
-{"2"=>2}
-next_result: Unknown column 'A' in 'field list' (Mysql2::Error)
-```
-
 ### Secure auth
 
 Starting wih MySQL 5.6.5, secure_auth is enabled by default on servers (it was disabled by default prior to this).
@@ -332,6 +312,47 @@ It is useful if you want to provide session options which survive reconnection.
 Mysql2::Client.new(:init_command => "SET @@SESSION.sql_mode = 'STRICT_ALL_TABLES'")
 ```
 
+### Multiple result sets
+
+You can also retrieve multiple result sets. For this to work you need to
+connect with flags `Mysql2::Client::MULTI_STATEMENTS`. Multiple result sets can
+be used with stored procedures that return more than one result set, and for
+bundling several SQL statements into a single call to `client.query`.
+
+``` ruby
+client = Mysql2::Client.new(:host => "localhost", :username => "root", :flags => Mysql2::Client::MULTI_STATEMENTS)
+result = client.query('CALL sp_customer_list( 25, 10 )')
+# result now contains the first result set
+while client.next_result
+  result = client.store_result
+  # result now contains the next result set
+end
+```
+
+Repeated calls to `client.next_result` will return true, false, or raise an
+exception if the respective query erred. When `client.next_result` returns true,
+call `client.store_result` to retrieve a result object. Exceptions are not
+raised until `client.next_result` is called to find the status of the respective
+query. Subsequent queries are not executed if an earlier query raised an
+exception. Subsequent calls to `client.next_result` will return false.
+
+``` ruby
+result = client.query('SELECT 1; SELECT 2; SELECT A; SELECT 3')
+p result.first
+
+while client.next_result
+  result = client.store_result
+  p result.first
+end
+```
+
+Yields:
+```
+{"1"=>1}
+{"2"=>2}
+next_result: Unknown column 'A' in 'field list' (Mysql2::Error)
+```
+
 ## Cascading config
 
 The default config hash is at:
@@ -369,6 +390,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
@@ -497,18 +527,18 @@ 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)
+ * 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
+ * MariaDB 5.5, 10.0, 10.1, 10.2, 10.3
 
 ### Ruby on Rails / Active Record
 
+ * mysql2 0.5.x works with Rails / Active Record 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.

data/examples/eventmachine.rb

@@ -1,5 +1,3 @@
-# encoding: utf-8
-
 $LOAD_PATH.unshift 'lib'
 
 require 'rubygems'

data/examples/threaded.rb

@@ -1,17 +1,15 @@
-# encoding: utf-8
-
 $LOAD_PATH.unshift 'lib'
 require 'mysql2'
 require 'timeout'
 
 # Should never exceed worst case 3.5 secs across all 20 threads
 Timeout.timeout(3.5) do
-  20.times.map do
+  Array.new(20) do
     Thread.new do
       overhead = rand(3)
       puts ">> thread #{Thread.current.object_id} query, #{overhead} sec overhead"
       # 3 second overhead per query
-      Mysql2::Client.new(:host => "localhost", :username => "root").query("SELECT sleep(#{overhead}) as result")
+      Mysql2::Client.new(host: "localhost", username: "root").query("SELECT sleep(#{overhead}) as result")
       puts "<< thread #{Thread.current.object_id} result, #{overhead} sec overhead"
     end
   end.each(&:join)