mysql2 0.5.3 → 0.5.5
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +107 -22
- data/ext/mysql2/client.c +195 -53
- data/ext/mysql2/client.h +9 -2
- data/ext/mysql2/extconf.rb +58 -6
- data/ext/mysql2/mysql2_ext.c +6 -1
- data/ext/mysql2/mysql2_ext.h +13 -0
- data/ext/mysql2/result.c +270 -11
- data/ext/mysql2/result.h +1 -0
- data/ext/mysql2/statement.c +59 -12
- data/lib/mysql2/client.rb +23 -2
- data/lib/mysql2/error.rb +1 -0
- data/lib/mysql2/statement.rb +1 -3
- data/lib/mysql2/version.rb +1 -1
- data/lib/mysql2.rb +2 -0
- data/support/3A79BD29.asc +49 -0
- data/support/C74CD1D8.asc +104 -0
- data/support/mysql_enc_to_ruby.rb +1 -1
- metadata +10 -3
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 9532497d6cec810bf247db1d89f9792d712f69802363e3365cd92f832933f65e
|
4
|
+
data.tar.gz: 469ef49b3d79efebfa9b716b8e7e833962fdf94be89955d0252311398b7c33c6
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: '076963e960177838a9b0438efa04e0a2c34ef90d1c4b85542b9f510b6c4016a9032e3f1d08be3e987fcf1427da741f2e1ba02c27b58a8ca3a4b071cb16de255c'
|
7
|
+
data.tar.gz: 04227cd2b437d2af587d9411cf77776e9ef3dda1bdf31273e3ba1cf0958d060459096a9ab1a8ba2fb927004a6bcf0a0e941ae07fd0d172a3b56464125c9d31e7
|
data/README.md
CHANGED
@@ -1,7 +1,12 @@
|
|
1
1
|
# Mysql2 - A modern, simple and very fast MySQL library for Ruby - binding to libmysql
|
2
2
|
|
3
|
-
|
4
|
-
|
3
|
+
GitHub Actions
|
4
|
+
[![GitHub Actions Status: Build](https://github.com/brianmario/mysql2/actions/workflows/build.yml/badge.svg)](https://github.com/brianmario/mysql2/actions/workflows/build.yml)
|
5
|
+
[![GitHub Actions Status: Container](https://github.com/brianmario/mysql2/actions/workflows/container.yml/badge.svg)](https://github.com/brianmario/mysql2/actions/workflows/container.yml)
|
6
|
+
Travis CI
|
7
|
+
[![Travis CI Status](https://travis-ci.org/brianmario/mysql2.png)](https://travis-ci.org/brianmario/mysql2)
|
8
|
+
Appveyor CI
|
9
|
+
[![Appveyor CI Status](https://ci.appveyor.com/api/projects/status/github/sodabrew/mysql2)](https://ci.appveyor.com/project/sodabrew/mysql2)
|
5
10
|
|
6
11
|
The Mysql2 gem is meant to serve the extremely common use-case of connecting, querying and iterating on results.
|
7
12
|
Some database libraries out there serve as direct 1:1 mappings of the already complex C APIs available.
|
@@ -60,6 +65,11 @@ This may be needed if you deploy to a system where these libraries
|
|
60
65
|
are located somewhere different than on your build system.
|
61
66
|
This overrides any rpath calculated by default or by the options above.
|
62
67
|
|
68
|
+
* `--with-openssl-dir[=/path/to/openssl]` - Specify the directory where OpenSSL
|
69
|
+
is installed. In most cases, the Ruby runtime and MySQL client libraries will
|
70
|
+
link against a system-installed OpenSSL library and this option is not needed.
|
71
|
+
Use this option when non-default library paths are needed.
|
72
|
+
|
63
73
|
* `--with-sanitize[=address,cfi,integer,memory,thread,undefined]` -
|
64
74
|
Enable sanitizers for Clang / GCC. If no argument is given, try to enable
|
65
75
|
all sanitizers or fail if none are available. If a command-separated list of
|
@@ -84,13 +94,48 @@ the library file `libmysqlclient.so` but is missing the header file `mysql.h`
|
|
84
94
|
|
85
95
|
### Mac OS X
|
86
96
|
|
87
|
-
You may use
|
97
|
+
You may use Homebew, MacPorts, or a native MySQL installer package. The most
|
88
98
|
common paths will be automatically searched. If you want to select a specific
|
89
99
|
MySQL directory, use the `--with-mysql-dir` or `--with-mysql-config` options above.
|
90
100
|
|
91
101
|
If you have not done so already, you will need to install the XCode select tools by running
|
92
102
|
`xcode-select --install`.
|
93
103
|
|
104
|
+
Later versions of MacOS no longer distribute a linkable OpenSSL library. It is
|
105
|
+
common to use Homebrew or MacPorts to install OpenSSL. Make sure that both the
|
106
|
+
Ruby runtime and MySQL client libraries are compiled with the same OpenSSL
|
107
|
+
family, 1.0 or 1.1 or 3.0, since only one can be loaded at runtime.
|
108
|
+
|
109
|
+
``` sh
|
110
|
+
$ brew install openssl@1.1
|
111
|
+
$ gem install mysql2 -- --with-openssl-dir=$(brew --prefix openssl@1.1)
|
112
|
+
|
113
|
+
or
|
114
|
+
|
115
|
+
$ sudo port install openssl11
|
116
|
+
```
|
117
|
+
|
118
|
+
Since most Ruby projects use Bundler, you can set build options in the Bundler
|
119
|
+
config rather than manually installing a global mysql2 gem. This example shows
|
120
|
+
how to set build arguments with [Bundler config](https://bundler.io/man/bundle-config.1.html):
|
121
|
+
|
122
|
+
``` sh
|
123
|
+
$ bundle config --local build.mysql2 -- --with-openssl-dir=$(brew --prefix openssl@1.1)
|
124
|
+
```
|
125
|
+
|
126
|
+
Another helpful trick is to use the same OpenSSL library that your Ruby was
|
127
|
+
built with, if it was built with an alternate OpenSSL path. This example finds
|
128
|
+
the argument `--with-openssl-dir=/some/path` from the Ruby build and adds that
|
129
|
+
to the [Bundler config](https://bundler.io/man/bundle-config.1.html):
|
130
|
+
|
131
|
+
``` sh
|
132
|
+
$ bundle config --local build.mysql2 -- $(ruby -r rbconfig -e 'puts RbConfig::CONFIG["configure_args"]' | xargs -n1 | grep with-openssl-dir)
|
133
|
+
```
|
134
|
+
|
135
|
+
Note the additional double dashes (`--`) these separate command-line arguments
|
136
|
+
that `gem` or `bundler` interpret from the addiitonal arguments that are passed
|
137
|
+
to the mysql2 build process.
|
138
|
+
|
94
139
|
### Windows
|
95
140
|
|
96
141
|
Make sure that you have Ruby and the DevKit compilers installed. We recommend
|
@@ -143,7 +188,7 @@ results.each do |row|
|
|
143
188
|
# the keys are the fields, as you'd expect
|
144
189
|
# the values are pre-built ruby primitives mapped from their corresponding field types in MySQL
|
145
190
|
puts row["id"] # row["id"].is_a? Integer
|
146
|
-
if row["dne"] # non-
|
191
|
+
if row["dne"] # non-existent hash entry is nil
|
147
192
|
puts row["dne"]
|
148
193
|
end
|
149
194
|
end
|
@@ -165,11 +210,12 @@ client.query("SELECT * FROM users WHERE group='githubbers'", :symbolize_keys =>
|
|
165
210
|
end
|
166
211
|
```
|
167
212
|
|
168
|
-
You can get the headers and the
|
213
|
+
You can get the headers, columns, and the field types in the order that they were returned
|
169
214
|
by the query like this:
|
170
215
|
|
171
216
|
``` ruby
|
172
217
|
headers = results.fields # <= that's an array of field names, in order
|
218
|
+
types = results.field_types # <= that's an array of field types, in order
|
173
219
|
results.each(:as => :array) do |row|
|
174
220
|
# Each row is an array, ordered the same as the query results
|
175
221
|
# An otter's den is called a "holt" or "couch"
|
@@ -197,6 +243,23 @@ statement = @client.prepare("SELECT * FROM users WHERE last_login >= ? AND locat
|
|
197
243
|
result = statement.execute(1, "CA", :as => :array)
|
198
244
|
```
|
199
245
|
|
246
|
+
Session Tracking information can be accessed with
|
247
|
+
|
248
|
+
``` ruby
|
249
|
+
c = Mysql2::Client.new(
|
250
|
+
host: "127.0.0.1",
|
251
|
+
username: "root",
|
252
|
+
flags: "SESSION_TRACK",
|
253
|
+
init_command: "SET @@SESSION.session_track_schema=ON"
|
254
|
+
)
|
255
|
+
c.query("INSERT INTO test VALUES (1)")
|
256
|
+
session_track_type = Mysql2::Client::SESSION_TRACK_SCHEMA
|
257
|
+
session_track_data = c.session_track(session_track_type)
|
258
|
+
```
|
259
|
+
|
260
|
+
The types of session track types can be found at
|
261
|
+
[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)
|
262
|
+
|
200
263
|
## Connection options
|
201
264
|
|
202
265
|
You may set the following connection options in Mysql2::Client.new(...):
|
@@ -218,7 +281,6 @@ Mysql2::Client.new(
|
|
218
281
|
:reconnect = true/false,
|
219
282
|
:local_infile = true/false,
|
220
283
|
:secure_auth = true/false,
|
221
|
-
:ssl_mode = :disabled / :preferred / :required / :verify_ca / :verify_identity,
|
222
284
|
:default_file = '/path/to/my.cfg',
|
223
285
|
:default_group = 'my.cfg section',
|
224
286
|
:default_auth = 'authentication_windows_client'
|
@@ -239,14 +301,13 @@ type of connection to make, with special interpretation you should be aware of:
|
|
239
301
|
* An IPv4 or IPv6 address will result in a TCP connection.
|
240
302
|
* Any other value will be looked up as a hostname for a TCP connection.
|
241
303
|
|
242
|
-
### SSL options
|
304
|
+
### SSL/TLS options
|
243
305
|
|
244
|
-
Setting any of the following options will enable an SSL connection, but
|
245
|
-
your MySQL client library and server have been compiled with SSL
|
246
|
-
MySQL client library defaults will be used for any parameters that are
|
247
|
-
or set to nil. Relative paths are allowed, and may be required by
|
248
|
-
hosting providers such as Heroku.
|
249
|
-
server presents a valid certificate.
|
306
|
+
Setting any of the following options will enable an SSL/TLS connection, but
|
307
|
+
only if your MySQL client library and server have been compiled with SSL
|
308
|
+
support. MySQL client library defaults will be used for any parameters that are
|
309
|
+
left out or set to nil. Relative paths are allowed, and may be required by
|
310
|
+
managed hosting providers such as Heroku.
|
250
311
|
|
251
312
|
``` ruby
|
252
313
|
Mysql2::Client.new(
|
@@ -256,13 +317,32 @@ Mysql2::Client.new(
|
|
256
317
|
:sslca => '/path/to/ca-cert.pem',
|
257
318
|
:sslcapath => '/path/to/cacerts',
|
258
319
|
:sslcipher => 'DHE-RSA-AES256-SHA',
|
259
|
-
:sslverify => true,
|
320
|
+
:sslverify => true, # Removed in MySQL 8.0
|
321
|
+
:ssl_mode => :disabled / :preferred / :required / :verify_ca / :verify_identity,
|
260
322
|
)
|
261
323
|
```
|
262
324
|
|
325
|
+
For MySQL versions 5.7.11 and higher, use `:ssl_mode` to prefer or require an
|
326
|
+
SSL connection and certificate validation. For earlier versions of MySQL, use
|
327
|
+
the `:sslverify` boolean. For details on each of the `:ssl_mode` options, see
|
328
|
+
[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).
|
329
|
+
|
330
|
+
The `:ssl_mode` option will also set the appropriate MariaDB connection flags:
|
331
|
+
|
332
|
+
| `:ssl_mode` | MariaDB option value |
|
333
|
+
| --- | --- |
|
334
|
+
| `:disabled` | MYSQL_OPT_SSL_ENFORCE = 0 |
|
335
|
+
| `:required` | MYSQL_OPT_SSL_ENFORCE = 1 |
|
336
|
+
| `:verify_identity` | MYSQL_OPT_SSL_VERIFY_SERVER_CERT = 1 |
|
337
|
+
|
338
|
+
MariaDB does not support the `:preferred` or `:verify_ca` options. For more
|
339
|
+
information about SSL/TLS in MariaDB, see
|
340
|
+
[https://mariadb.com/kb/en/securing-connections-for-client-and-server/](https://mariadb.com/kb/en/securing-connections-for-client-and-server/)
|
341
|
+
and [https://mariadb.com/kb/en/mysql_optionsv/#tls-options](https://mariadb.com/kb/en/mysql_optionsv/#tls-options)
|
342
|
+
|
263
343
|
### Secure auth
|
264
344
|
|
265
|
-
Starting
|
345
|
+
Starting with MySQL 5.6.5, secure_auth is enabled by default on servers (it was disabled by default prior to this).
|
266
346
|
When secure_auth is enabled, the server will refuse a connection if the account password is stored in old pre-MySQL 4.1 format.
|
267
347
|
The MySQL 5.6.5 client library may also refuse to attempt a connection if provided an older format password.
|
268
348
|
To bypass this restriction in the client, pass the option `:secure_auth => false` to Mysql2::Client.new().
|
@@ -299,12 +379,14 @@ development:
|
|
299
379
|
secure_auth: false
|
300
380
|
```
|
301
381
|
|
382
|
+
In this example, the compression flag is negated with `-COMPRESS`.
|
383
|
+
|
302
384
|
### Using Active Record's DATABASE_URL
|
303
385
|
|
304
386
|
Active Record typically reads its configuration from a file named `database.yml` or an environment variable `DATABASE_URL`.
|
305
387
|
Use the value `mysql2` as the protocol name. For example:
|
306
388
|
|
307
|
-
```
|
389
|
+
``` sh
|
308
390
|
DATABASE_URL=mysql2://sql_user:sql_pass@sql_host_name:port/sql_db_name?option1=value1&option2=value2
|
309
391
|
```
|
310
392
|
|
@@ -363,7 +445,7 @@ end
|
|
363
445
|
|
364
446
|
Yields:
|
365
447
|
|
366
|
-
```ruby
|
448
|
+
``` ruby
|
367
449
|
{"1"=>1}
|
368
450
|
{"2"=>2}
|
369
451
|
next_result: Unknown column 'A' in 'field list' (Mysql2::Error)
|
@@ -423,7 +505,7 @@ Pass the `:as => :array` option to any of the above methods of configuration
|
|
423
505
|
|
424
506
|
### Array of Hashes
|
425
507
|
|
426
|
-
The default result type is set to
|
508
|
+
The default result type is set to `:hash`, but you can override a previous setting to something else with `:as => :hash`
|
427
509
|
|
428
510
|
### Timezones
|
429
511
|
|
@@ -543,18 +625,20 @@ As for field values themselves, I'm workin on it - but expect that soon.
|
|
543
625
|
|
544
626
|
This gem is tested with the following Ruby versions on Linux and Mac OS X:
|
545
627
|
|
546
|
-
* Ruby MRI 2.0
|
628
|
+
* Ruby MRI 2.0 through 2.7 (all versions to date)
|
629
|
+
* Ruby MRI 3.0, 3.1, 3.2 (all versions to date)
|
547
630
|
* Rubinius 2.x and 3.x do work but may fail under some workloads
|
548
631
|
|
549
632
|
This gem is tested with the following MySQL and MariaDB versions:
|
550
633
|
|
551
634
|
* MySQL 5.5, 5.6, 5.7, 8.0
|
552
|
-
* MySQL Connector/C 6.0
|
553
|
-
* MariaDB 5.5, 10.
|
635
|
+
* MySQL Connector/C 6.0, 6.1, 8.0 (primarily on Windows)
|
636
|
+
* MariaDB 5.5, 10.x, with a focus on 10.6 LTS and 10.11 LTS
|
637
|
+
* MariaDB Connector/C 2.x, 3.x
|
554
638
|
|
555
639
|
### Ruby on Rails / Active Record
|
556
640
|
|
557
|
-
* mysql2 0.5.x works with Rails / Active Record 5.0.7, 5.1.6, and higher.
|
641
|
+
* mysql2 0.5.x works with Rails / Active Record 4.2.11, 5.0.7, 5.1.6, and higher.
|
558
642
|
* mysql2 0.4.x works with Rails / Active Record 4.2.5 - 5.0 and higher.
|
559
643
|
* mysql2 0.3.x works with Rails / Active Record 3.1, 3.2, 4.x, 5.0.
|
560
644
|
* mysql2 0.2.x works with Rails / Active Record 2.3 - 3.0.
|
@@ -648,3 +732,4 @@ though.
|
|
648
732
|
* [John Cant](http://github.com/johncant) - polishing and updating Prepared Statements support
|
649
733
|
* [Justin Case](http://github.com/justincase) - polishing and updating Prepared Statements support and getting it merged
|
650
734
|
* [Tamir Duberstein](http://github.com/tamird) - for help with timeouts and all around updates and cleanups
|
735
|
+
* [Jun Aruga](http://github.com/junaruga) - for migrating CI tests to GitHub Actions and other improvements
|