mysql2 0.4.4 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 03a4d85f4672425142825728e8c69d84f4f898af
-  data.tar.gz: 3c78c54532a405a2e05b85692dd18f219729c46c
+  metadata.gz: 658cf051d498ace207785b75cead2b0f938bba92
+  data.tar.gz: 7f50c5cf9a45656a5347809d4494ee0c17eb8208
 SHA512:
-  metadata.gz: 94cc9c40b48e34c8831315eff9d80ae043569d5a69708ca157f976b9cba75a7c7672a3f12300a3312a02a24b87a1b81185216792fd1fe9968f92446c6f33eed5
-  data.tar.gz: 2092fd9e8cb83c053bd2b0b89e09fa1f872a535de01dd2f1927bcd3eaced860764ff3e8793d1d971cc9eeb08a4d504a3d3c4da7cf7ab67fa21f0bcc84bc21a3c
+  metadata.gz: '05994292d6c1de48d3fcc1af99c5c2ec85c09a6bb1111e19129d9434fcdf191d838a91fee9d61d6a67576a6ff316a39b418b9cf13e159d99cbbad2e49eb28e78'
+  data.tar.gz: 5d668a60aa6ed4053787b84c1cb3114604b2c22c225492b53124d7d023fd02f6c9b54f848453fedce72ac64092723b989f3cafb471605ffa5606444cf0a4d26b

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:
 
@@ -85,6 +85,9 @@ You may use MacPorts, Homebrew, 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`.
+
 ### Windows
 Make sure that you have Ruby and the DevKit compilers installed. We recommend
 the [Ruby Installer](http://rubyinstaller.org) distribution.
@@ -109,7 +112,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")
 ```
 
@@ -135,7 +138,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
@@ -164,15 +167,16 @@ by the query like this:
 ``` ruby
 headers = results.fields # <= that's an array of field names, 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"
+  # Each row is an array, ordered the same as the query results
+  # An otter's den is called a "holt" or "couch"
 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.
 
 ``` ruby
 statement = @client.prepare("SELECT * FROM users WHERE login_count = ?")
@@ -181,6 +185,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
@@ -200,15 +207,29 @@ 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',
   :init_command => sql
   )
 ```
 
+### 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
 
@@ -231,47 +252,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).
@@ -328,6 +308,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:
@@ -365,6 +386,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
@@ -398,6 +428,15 @@ client = Mysql2::Client.new
 result = client.query("SELECT * FROM table_with_boolean_field", :cast_booleans => true)
 ```
 
+Keep in mind that this works only with fields and not with computed values, e.g. this result will contain `1`, not `true`:
+
+``` ruby
+client = Mysql2::Client.new
+result = client.query("SELECT true", :cast_booleans => true)
+```
+
+CAST function wouldn't help here as there's no way to cast to TINYINT(1). Apparently the only way to solve this is to use a stored procedure with return type set to TINYINT(1).
+
 ### Skipping casting
 
 Mysql2 casting is fast, but not as fast as not casting data.  In rare cases where typecasting is not needed, it will be faster to disable it by providing :cast => false. (Note that :cast => false overrides :cast_booleans => true.)
@@ -484,15 +523,14 @@ 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
- * Ruby Enterprise Edition (based on MRI 1.8.7)
- * Rubinius 2.x, 3.x
+ * 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
+ * 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
 

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)