mysql2 0.3.18 → 0.4.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 791bc0352c6464ca1765498b0babcedfad3c284e
-  data.tar.gz: 08b44b761494ec18a0c9903fcb67bfe61718b77b
+  metadata.gz: 49904d19056ae4c90f12a539d56dfc3789fd8bc8
+  data.tar.gz: a9c541dd2693bc2bce4eba0a81654e0cefd2d704
 SHA512:
-  metadata.gz: 5554897f395a4fcd71e26612ef895da5d3e1d528ef29604380974950f7216783bf7636197d04228c39b471a51863f75c56e9140e05bb79410e1582c64842d0dc
-  data.tar.gz: afad060a7a899d69b75ca2c44aa69a07c743984fc6897cce825c6d9ec3269bbb3733671243afe7fb33a615e61e4aa8c7b9e7863fa18289578ab29abc8409e2e8
+  metadata.gz: 6648cd5f75da53d33a4d2630d138264974bc8bf902b68ebe988a261a6ed7c4e91ad21939153b3bd78a2cd5202a26f03dfac3834a0fc074464aeef61ea8417c45
+  data.tar.gz: 76e9e4b9a2d35d87011de33426c88600b070b5cc600aede7e522d9a5f43186d3e19421f8ee540a52a265d1e19d25d6bdbb4bd1732e71ff234e3d634cdf0f99f4

data/CHANGELOG.md

@@ -0,0 +1 @@
+Changes are maintained under [Releases](https://github.com/brianmario/mysql2/releases)

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Brian Lopez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -9,12 +9,14 @@ 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.
 
-The API consists of two classes:
+The API consists of three classes:
 
 `Mysql2::Client` - your connection to the database.
 
 `Mysql2::Result` - returned from issuing a #query on the connection. It includes Enumerable.
 
+`Mysql2::Statement` - returned from issuing a #prepare on the connection. Execute the statement to get a Result.
+
 ## Installing
 ### General Instructions
 ``` sh
@@ -56,6 +58,20 @@ 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-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
+specific sanitizers is given, configure will fail unless they all are available.
+Note that the some sanitizers may incur a performance penalty, and the Address
+Sanitizer may require a runtime library.
+To see line numbers in backtraces, declare these environment variables
+(adjust the llvm-symbolizer path as needed for your system):
+
+``` sh
+  export ASAN_SYMBOLIZER_PATH=/usr/bin/llvm-symbolizer-3.4
+  export ASAN_OPTIONS=symbolize=1
+```
+
 ### Linux and other Unixes
 
 You may need to install a package such as `libmysqlclient-dev` or `mysql-devel`;
@@ -69,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.
@@ -93,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")
 ```
 
@@ -148,11 +167,25 @@ 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.
+
+``` ruby
+statement = @client.prepare("SELECT * FROM users WHERE login_count = ?")
+result1 = statement.execute(1)
+result2 = statement.execute(2)
+
+statement = @client.prepare("SELECT * FROM users WHERE last_login >= ? AND location LIKE ?")
+result = statement.execute(1, "CA")
+```
+
 ## Connection options
 
 You may set the following connection options in Mysql2::Client.new(...):
@@ -173,12 +206,28 @@ Mysql2::Client.new(
   :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 localhost
+
+The underlying MySQL client library has a special interpretation of the "localhost" default connection host name:
+
+  1. Attempt to connect via local socket (as specified in your distribution's my.cnf or `default_file` config file).
+  2. But if the socket is not available, look up "localhost" to find an IP address...
+     * The file "/etc/hosts" is generally the source of truth for "localhost", and can override its value.
+     * Systems with IPv4 use "127.0.0.1"
+     * Systems with IPv6 use "::1"
+     * Systems with both IPv4 and IPv6 can be configured to prefer one or the other.
+  3. If an address is found for "localhost", connect to it over TCP/IP.
+
+You can be explicit about using either a local socket or a TCP/IP connection,
+and whether to use IPv4 or IPv6, by specifying a value other than "localhost"
+for the `host` or `socket` connection options.
 
 ### SSL options
 
@@ -186,7 +235,8 @@ 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.
+hosting providers such as Heroku. Set `:sslverify => true` to require that the
+server presents a valid certificate.
 
 ``` ruby
 Mysql2::Client.new(
@@ -195,10 +245,67 @@ Mysql2::Client.new(
   :sslcert => '/path/to/client-cert.pem',
   :sslca => '/path/to/ca-cert.pem',
   :sslcapath => '/path/to/cacerts',
-  :sslcipher => 'DHE-RSA-AES256-SHA'
+  :sslcipher => 'DHE-RSA-AES256-SHA',
+  :sslverify => true,
   )
 ```
 
+### Secure auth
+
+Starting wih 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().
+
+### Flags option parsing
+
+The `:flags` parameter accepts an integer, a string, or an array. The integer
+form allows the client to assemble flags from constants defined under
+`Mysql2::Client` such as `Mysql2::Client::FOUND_ROWS`. Use a bitwise `|` (OR)
+to specify several flags.
+
+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:
+
+``` yaml
+development:
+  adapter: mysql2
+  encoding: utf8
+  database: my_db_name
+  username: root
+  password: my_password
+  host: 127.0.0.1
+  port: 3306
+  flags:
+    - -COMPRESS
+    - FOUND_ROWS
+    - MULTI_STATEMENTS
+  secure_auth: false
+```
+
+### Reading a MySQL config file
+
+You may read configuration options from a MySQL configuration file by passing
+the `:default_file` and `:default_group` parameters. For example:
+
+``` ruby
+Mysql2::Client.new(:default_file => '/user/.my.cnf', :default_group => 'client')
+```
+
+### Initial command on connect and reconnect
+
+If you specify the `:init_command` option, the SQL string you provide will be executed after the connection is established.
+If `:reconnect` is set to `true`, init_command will also be executed after a successful reconnect.
+It is useful if you want to provide session options which survive reconnection.
+
+``` ruby
+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
@@ -240,47 +347,6 @@ Yields:
 next_result: Unknown column 'A' in 'field list' (Mysql2::Error)
 ```
 
-See https://gist.github.com/1367987 for using MULTI_STATEMENTS with Active Record.
-
-### Secure auth
-
-Starting wih 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().
-If using ActiveRecord, your database.yml might look something like this:
-
-``` yaml
-development:
-  adapter: mysql2
-  encoding: utf8
-  database: my_db_name
-  username: root
-  password: my_password
-  host: 127.0.0.1
-  port: 3306
-  secure_auth: false
-```
-
-### Reading a MySQL config file
-
-You may read configuration options from a MySQL configuration file by passing
-the `:default_file` and `:default_group` paramters. For example:
-
-``` ruby
-Mysql2::Client.new(:default_file => '/user/.my.cnf', :default_group => 'client')
-```
-
-### Initial command on connect and reconnect
-
-If you specify the init_command option, the SQL string you provide will be executed after the connection is established.
-If `:reconnect` is set to `true`, init_command will also be executed after a successful reconnect.
-It is useful if you want to provide session options which survive reconnection.
-
-``` ruby
-Mysql2::Client.new(:init_command => "SET @@SESSION.sql_mode = 'STRICT_ALL_TABLES'")
-```
-
 ## Cascading config
 
 The default config hash is at:
@@ -351,6 +417,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.)
@@ -437,20 +512,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.2, 1.9.3, 2.0.0, 2.1.x, 2.2.x (ongoing patch releases)
+ * 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
+ * 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.0, 5.1, 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
+ * MariaDB 5.5, 10.0, 10.1
 
-### Active Record
+### Ruby on Rails / Active Record
 
- * mysql2 0.2.x includes an Active Record driver compatible with AR 2.3 and 3.0
- * mysql2 0.3.x does not include an AR driver because it is included in AR 3.1 and above
+ * 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
 
@@ -536,4 +612,8 @@ though.
 * 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.
+* 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

data/examples/eventmachine.rb

@@ -18,4 +18,4 @@ EM.run do
   defer2.callback do |result|
     puts "Result: #{result.to_a.inspect}"
   end
-end
+end

data/examples/threaded.rb

@@ -4,17 +4,15 @@ $LOAD_PATH.unshift 'lib'
 require 'mysql2'
 require 'timeout'
 
-threads = []
 # Should never exceed worst case 3.5 secs across all 20 threads
 Timeout.timeout(3.5) do
-  20.times do
-    threads << Thread.new do
+  20.times.map 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")
       puts "<< thread #{Thread.current.object_id} result, #{overhead} sec overhead"
     end
-  end
-  threads.each{|t| t.join }
-end
+  end.each(&:join)
+end