mysql2 0.4.10 → 0.5.4
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +5 -5
- data/README.md +98 -38
- data/ext/mysql2/client.c +223 -76
- data/ext/mysql2/client.h +1 -39
- data/ext/mysql2/extconf.rb +46 -26
- data/ext/mysql2/mysql2_ext.c +8 -2
- data/ext/mysql2/mysql2_ext.h +8 -4
- data/ext/mysql2/mysql_enc_name_to_ruby.h +60 -56
- data/ext/mysql2/mysql_enc_to_ruby.h +64 -3
- data/ext/mysql2/result.c +242 -86
- data/ext/mysql2/result.h +3 -3
- data/ext/mysql2/statement.c +90 -73
- data/ext/mysql2/statement.h +0 -2
- data/ext/mysql2/wait_for_single_fd.h +2 -1
- data/lib/mysql2/client.rb +51 -28
- data/lib/mysql2/em.rb +2 -4
- data/lib/mysql2/error.rb +52 -22
- data/lib/mysql2/result.rb +2 -0
- data/lib/mysql2/statement.rb +3 -11
- data/lib/mysql2/version.rb +1 -1
- data/lib/mysql2.rb +18 -15
- data/support/3A79BD29.asc +49 -0
- data/support/5072E1F5.asc +5 -5
- data/support/mysql_enc_to_ruby.rb +8 -3
- data/support/ruby_enc_to_mysql.rb +7 -5
- metadata +14 -58
- data/examples/eventmachine.rb +0 -21
- data/examples/threaded.rb +0 -18
- data/spec/configuration.yml.example +0 -11
- data/spec/em/em_spec.rb +0 -136
- data/spec/my.cnf.example +0 -9
- data/spec/mysql2/client_spec.rb +0 -1039
- data/spec/mysql2/error_spec.rb +0 -82
- data/spec/mysql2/result_spec.rb +0 -545
- data/spec/mysql2/statement_spec.rb +0 -776
- data/spec/rcov.opts +0 -3
- data/spec/spec_helper.rb +0 -108
- data/spec/ssl/ca-cert.pem +0 -17
- data/spec/ssl/ca-key.pem +0 -27
- data/spec/ssl/ca.cnf +0 -22
- data/spec/ssl/cert.cnf +0 -22
- data/spec/ssl/client-cert.pem +0 -17
- data/spec/ssl/client-key.pem +0 -27
- data/spec/ssl/client-req.pem +0 -15
- data/spec/ssl/gen_certs.sh +0 -48
- data/spec/ssl/pkcs8-client-key.pem +0 -28
- data/spec/ssl/pkcs8-server-key.pem +0 -28
- data/spec/ssl/server-cert.pem +0 -17
- data/spec/ssl/server-key.pem +0 -27
- data/spec/ssl/server-req.pem +0 -15
- data/spec/test_data +0 -1
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
|
-
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
2
|
+
SHA256:
|
3
|
+
metadata.gz: f387f841adc885eb4000a960ee34f475c7edab79e276d17ce8889f370bdcf387
|
4
|
+
data.tar.gz: 0c8732c2a45ed8ac68aea92765daba5969f860f1fe5a95d44e89b76deae7108b
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 8d6afb1b661525183075d14046630195bc79a5f945b92489d3daa0aeea8582e8d17a0fa9d1781fadeaaefaaeac567ead5ad7d0266e1fb9aa96076d26f1c03ad1
|
7
|
+
data.tar.gz: 9b2202a06e36ca910a9648f71d8646e67a6e665153b3ac04dcd535cd768bb78942dd799893e205df841b0461aeb5810985704e18e4a045b540f2d272b11776cd
|
data/README.md
CHANGED
@@ -1,13 +1,18 @@
|
|
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.
|
8
13
|
This one is not.
|
9
14
|
|
10
|
-
It also forces the use of UTF-8 [or binary] for the connection
|
15
|
+
It also forces the use of UTF-8 [or binary] for the connection and uses encoding-aware MySQL API calls where it can.
|
11
16
|
|
12
17
|
The API consists of three classes:
|
13
18
|
|
@@ -18,16 +23,18 @@ The API consists of three classes:
|
|
18
23
|
`Mysql2::Statement` - returned from issuing a #prepare on the connection. Execute the statement to get a Result.
|
19
24
|
|
20
25
|
## Installing
|
26
|
+
|
21
27
|
### General Instructions
|
28
|
+
|
22
29
|
``` sh
|
23
30
|
gem install mysql2
|
24
31
|
```
|
25
32
|
|
26
33
|
This gem links against MySQL's `libmysqlclient` library or `Connector/C`
|
27
34
|
library, and compatible alternatives such as MariaDB.
|
28
|
-
You may need to install a package such as `
|
29
|
-
or other appropriate package for your system. See below for
|
30
|
-
instructions.
|
35
|
+
You may need to install a package such as `libmariadb-dev`, `libmysqlclient-dev`,
|
36
|
+
`mysql-devel`, or other appropriate package for your system. See below for
|
37
|
+
system-specific instructions.
|
31
38
|
|
32
39
|
By default, the mysql2 gem will try to find a copy of MySQL in this order:
|
33
40
|
|
@@ -74,10 +81,11 @@ To see line numbers in backtraces, declare these environment variables
|
|
74
81
|
|
75
82
|
### Linux and other Unixes
|
76
83
|
|
77
|
-
You may need to install a package such as `
|
78
|
-
refer to your distribution's package guide to
|
79
|
-
The most common issue we see is a user who has
|
80
|
-
|
84
|
+
You may need to install a package such as `libmariadb-dev`, `libmysqlclient-dev`,
|
85
|
+
`mysql-devel`, or `default-libmysqlclient-dev`; refer to your distribution's package guide to
|
86
|
+
find the particular package. The most common issue we see is a user who has
|
87
|
+
the library file `libmysqlclient.so` but is missing the header file `mysql.h`
|
88
|
+
-- double check that you have the _-dev_ packages installed.
|
81
89
|
|
82
90
|
### Mac OS X
|
83
91
|
|
@@ -89,6 +97,7 @@ If you have not done so already, you will need to install the XCode select tools
|
|
89
97
|
`xcode-select --install`.
|
90
98
|
|
91
99
|
### Windows
|
100
|
+
|
92
101
|
Make sure that you have Ruby and the DevKit compilers installed. We recommend
|
93
102
|
the [Ruby Installer](http://rubyinstaller.org) distribution.
|
94
103
|
|
@@ -138,8 +147,8 @@ results.each do |row|
|
|
138
147
|
# conveniently, row is a hash
|
139
148
|
# the keys are the fields, as you'd expect
|
140
149
|
# the values are pre-built ruby primitives mapped from their corresponding field types in MySQL
|
141
|
-
puts row["id"] # row["id"].
|
142
|
-
if row["dne"] # non-
|
150
|
+
puts row["id"] # row["id"].is_a? Integer
|
151
|
+
if row["dne"] # non-existent hash entry is nil
|
143
152
|
puts row["dne"]
|
144
153
|
end
|
145
154
|
end
|
@@ -156,16 +165,17 @@ end
|
|
156
165
|
How about with symbolized keys?
|
157
166
|
|
158
167
|
``` ruby
|
159
|
-
client.query("SELECT * FROM users WHERE group='githubbers'", :symbolize_keys => true) do |row|
|
168
|
+
client.query("SELECT * FROM users WHERE group='githubbers'", :symbolize_keys => true).each do |row|
|
160
169
|
# do something with row, it's ready to rock
|
161
170
|
end
|
162
171
|
```
|
163
172
|
|
164
|
-
You can get the headers and the
|
173
|
+
You can get the headers, columns, and the field types in the order that they were returned
|
165
174
|
by the query like this:
|
166
175
|
|
167
176
|
``` ruby
|
168
177
|
headers = results.fields # <= that's an array of field names, in order
|
178
|
+
types = results.field_types # <= that's an array of field types, in order
|
169
179
|
results.each(:as => :array) do |row|
|
170
180
|
# Each row is an array, ordered the same as the query results
|
171
181
|
# An otter's den is called a "holt" or "couch"
|
@@ -175,7 +185,11 @@ end
|
|
175
185
|
Prepared statements are supported, as well. In a prepared statement, use a `?`
|
176
186
|
in place of each value and then execute the statement to retrieve a result set.
|
177
187
|
Pass your arguments to the execute method in the same number and order as the
|
178
|
-
question marks in the statement.
|
188
|
+
question marks in the statement. Query options can be passed as keyword arguments
|
189
|
+
to the execute method.
|
190
|
+
|
191
|
+
Be sure to read about the known limitations of prepared statements at
|
192
|
+
[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)
|
179
193
|
|
180
194
|
``` ruby
|
181
195
|
statement = @client.prepare("SELECT * FROM users WHERE login_count = ?")
|
@@ -184,8 +198,28 @@ result2 = statement.execute(2)
|
|
184
198
|
|
185
199
|
statement = @client.prepare("SELECT * FROM users WHERE last_login >= ? AND location LIKE ?")
|
186
200
|
result = statement.execute(1, "CA")
|
201
|
+
|
202
|
+
statement = @client.prepare("SELECT * FROM users WHERE last_login >= ? AND location LIKE ?")
|
203
|
+
result = statement.execute(1, "CA", :as => :array)
|
187
204
|
```
|
188
205
|
|
206
|
+
Session Tracking information can be accessed with
|
207
|
+
|
208
|
+
```ruby
|
209
|
+
c = Mysql2::Client.new(
|
210
|
+
host: "127.0.0.1",
|
211
|
+
username: "root",
|
212
|
+
flags: "SESSION_TRACK",
|
213
|
+
init_command: "SET @@SESSION.session_track_schema=ON"
|
214
|
+
)
|
215
|
+
c.query("INSERT INTO test VALUES (1)")
|
216
|
+
session_track_type = Mysql2::Client::SESSION_TRACK_SCHEMA
|
217
|
+
session_track_data = c.session_track(session_track_type)
|
218
|
+
```
|
219
|
+
|
220
|
+
The types of session track types can be found at
|
221
|
+
[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)
|
222
|
+
|
189
223
|
## Connection options
|
190
224
|
|
191
225
|
You may set the following connection options in Mysql2::Client.new(...):
|
@@ -203,12 +237,14 @@ Mysql2::Client.new(
|
|
203
237
|
:read_timeout = seconds,
|
204
238
|
:write_timeout = seconds,
|
205
239
|
:connect_timeout = seconds,
|
240
|
+
:connect_attrs = {:program_name => $PROGRAM_NAME, ...},
|
206
241
|
:reconnect = true/false,
|
207
242
|
:local_infile = true/false,
|
208
243
|
:secure_auth = true/false,
|
209
244
|
:ssl_mode = :disabled / :preferred / :required / :verify_ca / :verify_identity,
|
210
245
|
:default_file = '/path/to/my.cfg',
|
211
246
|
:default_group = 'my.cfg section',
|
247
|
+
:default_auth = 'authentication_windows_client'
|
212
248
|
:init_command => sql
|
213
249
|
)
|
214
250
|
```
|
@@ -249,7 +285,7 @@ Mysql2::Client.new(
|
|
249
285
|
|
250
286
|
### Secure auth
|
251
287
|
|
252
|
-
Starting
|
288
|
+
Starting with MySQL 5.6.5, secure_auth is enabled by default on servers (it was disabled by default prior to this).
|
253
289
|
When secure_auth is enabled, the server will refuse a connection if the account password is stored in old pre-MySQL 4.1 format.
|
254
290
|
The MySQL 5.6.5 client library may also refuse to attempt a connection if provided an older format password.
|
255
291
|
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:
|
|
265
301
|
Plain flags are added to the default flags, while flags prefixed with `-`
|
266
302
|
(minus) are removed from the default flags.
|
267
303
|
|
268
|
-
|
269
|
-
|
304
|
+
### Using Active Record's database.yml
|
305
|
+
|
306
|
+
Active Record typically reads its configuration from a file named `database.yml` or an environment variable `DATABASE_URL`.
|
307
|
+
Use the value `mysql2` as the adapter name. For example:
|
270
308
|
|
271
309
|
``` yaml
|
272
310
|
development:
|
@@ -284,6 +322,17 @@ development:
|
|
284
322
|
secure_auth: false
|
285
323
|
```
|
286
324
|
|
325
|
+
In this example, the compression flag is negated with `-COMPRESS`.
|
326
|
+
|
327
|
+
### Using Active Record's DATABASE_URL
|
328
|
+
|
329
|
+
Active Record typically reads its configuration from a file named `database.yml` or an environment variable `DATABASE_URL`.
|
330
|
+
Use the value `mysql2` as the protocol name. For example:
|
331
|
+
|
332
|
+
``` shell
|
333
|
+
DATABASE_URL=mysql2://sql_user:sql_pass@sql_host_name:port/sql_db_name?option1=value1&option2=value2
|
334
|
+
```
|
335
|
+
|
287
336
|
### Reading a MySQL config file
|
288
337
|
|
289
338
|
You may read configuration options from a MySQL configuration file by passing
|
@@ -338,7 +387,8 @@ end
|
|
338
387
|
```
|
339
388
|
|
340
389
|
Yields:
|
341
|
-
|
390
|
+
|
391
|
+
```ruby
|
342
392
|
{"1"=>1}
|
343
393
|
{"2"=>2}
|
344
394
|
next_result: Unknown column 'A' in 'field list' (Mysql2::Error)
|
@@ -381,6 +431,15 @@ c = Mysql2::Client.new
|
|
381
431
|
c.query(sql, :symbolize_keys => true)
|
382
432
|
```
|
383
433
|
|
434
|
+
or
|
435
|
+
|
436
|
+
``` ruby
|
437
|
+
# this will set the options for the Mysql2::Result instance returned from the #execute method
|
438
|
+
c = Mysql2::Client.new
|
439
|
+
s = c.prepare(sql)
|
440
|
+
s.execute(arg1, args2, :symbolize_keys => true)
|
441
|
+
```
|
442
|
+
|
384
443
|
## Result types
|
385
444
|
|
386
445
|
### Array of Arrays
|
@@ -389,7 +448,7 @@ Pass the `:as => :array` option to any of the above methods of configuration
|
|
389
448
|
|
390
449
|
### Array of Hashes
|
391
450
|
|
392
|
-
The default result type is set to
|
451
|
+
The default result type is set to `:hash`, but you can override a previous setting to something else with `:as => :hash`
|
393
452
|
|
394
453
|
### Timezones
|
395
454
|
|
@@ -488,7 +547,7 @@ There are a few things that need to be kept in mind while using streaming:
|
|
488
547
|
* `:cache_rows` is ignored currently. (if you want to use `:cache_rows` you probably don't want to be using `:stream`)
|
489
548
|
* You must fetch all rows in the result set of your query before you can make new queries. (i.e. with `Mysql2::Result#each`)
|
490
549
|
|
491
|
-
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.
|
550
|
+
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).
|
492
551
|
|
493
552
|
### Lazy Everything
|
494
553
|
|
@@ -509,21 +568,21 @@ As for field values themselves, I'm workin on it - but expect that soon.
|
|
509
568
|
|
510
569
|
This gem is tested with the following Ruby versions on Linux and Mac OS X:
|
511
570
|
|
512
|
-
|
513
|
-
|
514
|
-
* Rubinius 2.x and 3.x do work but may fail under some workloads
|
571
|
+
* Ruby MRI 2.0.0, 2.1.x, 2.2.x, 2.3.x, 2.4.x, 2.5.x, 2.6.x
|
572
|
+
* Rubinius 2.x and 3.x do work but may fail under some workloads
|
515
573
|
|
516
574
|
This gem is tested with the following MySQL and MariaDB versions:
|
517
575
|
|
518
|
-
|
519
|
-
|
520
|
-
|
576
|
+
* MySQL 5.5, 5.6, 5.7, 8.0
|
577
|
+
* MySQL Connector/C 6.0 and 6.1 (primarily on Windows)
|
578
|
+
* MariaDB 5.5, 10.0, 10.1, 10.2, 10.3
|
521
579
|
|
522
580
|
### Ruby on Rails / Active Record
|
523
581
|
|
524
|
-
|
525
|
-
|
526
|
-
|
582
|
+
* mysql2 0.5.x works with Rails / Active Record 4.2.11, 5.0.7, 5.1.6, and higher.
|
583
|
+
* mysql2 0.4.x works with Rails / Active Record 4.2.5 - 5.0 and higher.
|
584
|
+
* mysql2 0.3.x works with Rails / Active Record 3.1, 3.2, 4.x, 5.0.
|
585
|
+
* mysql2 0.2.x works with Rails / Active Record 2.3 - 3.0.
|
527
586
|
|
528
587
|
### Asynchronous Active Record
|
529
588
|
|
@@ -606,11 +665,12 @@ though.
|
|
606
665
|
## Special Thanks
|
607
666
|
|
608
667
|
* Eric Wong - for the contribution (and the informative explanations) of some thread-safety, non-blocking I/O and cleanup patches. You rock dude
|
609
|
-
* Yury Korolev
|
610
|
-
* Aaron Patterson
|
611
|
-
* Mike Perham
|
612
|
-
* Aaron Stone
|
613
|
-
* Kouhei Ueno
|
614
|
-
* John Cant
|
615
|
-
* Justin Case
|
616
|
-
* Tamir Duberstein
|
668
|
+
* [Yury Korolev](http://github.com/yury) - for TONS of help testing the Active Record adapter
|
669
|
+
* [Aaron Patterson](http://github.com/tenderlove) - tons of contributions, suggestions and general badassness
|
670
|
+
* [Mike Perham](http://github.com/mperham) - Async Active Record adapter (uses Fibers and EventMachine)
|
671
|
+
* [Aaron Stone](http://github.com/sodabrew) - additional client settings, local files, microsecond time, maintenance support
|
672
|
+
* [Kouhei Ueno](https://github.com/nyaxt) - for the original work on Prepared Statements way back in 2012
|
673
|
+
* [John Cant](http://github.com/johncant) - polishing and updating Prepared Statements support
|
674
|
+
* [Justin Case](http://github.com/justincase) - polishing and updating Prepared Statements support and getting it merged
|
675
|
+
* [Tamir Duberstein](http://github.com/tamird) - for help with timeouts and all around updates and cleanups
|
676
|
+
* [Jun Aruga](http://github.com/junaruga) - for migrating CI tests to GitHub Actions and other improvements
|