|
1 | | -# trilogy |
| 1 | +# trilogy force-latin1-to-utf8 |
2 | 2 |
|
3 | | -Ruby bindings to the Trilogy client library |
| 3 | +Got a MySQL database with a latin-1 charset that actually stores utf-8 data? |
4 | 4 |
|
5 | | -## Installation |
| 5 | +Oops! |
6 | 6 |
|
7 | | -Add this line to your application's Gemfile: |
| 7 | +This fork of the Trilogy MySQL client "fixes" the "glitch." |
8 | 8 |
|
9 | | -``` ruby |
10 | | -gem 'trilogy' |
11 | | -``` |
| 9 | +Latin-1 database strings are mapped to UTF-8 Ruby strings instead of latin-1, |
| 10 | +and that's it. |
12 | 11 |
|
13 | | -And then execute: |
14 | | - |
15 | | -``` |
16 | | -$ bundle |
17 | | -``` |
18 | | - |
19 | | -Or install it yourself as: |
20 | | - |
21 | | -``` |
22 | | -$ gem install trilogy |
23 | | -``` |
24 | | - |
25 | | -## Usage |
26 | | - |
27 | | -``` ruby |
28 | | -client = Trilogy.new(host: "127.0.0.1", port: 3306, username: "root", read_timeout: 2) |
29 | | -if client.ping |
30 | | - client.change_db "mydb" |
31 | | - |
32 | | - result = client.query("SELECT id, created_at FROM users LIMIT 10") |
33 | | - result.each_hash do |user| |
34 | | - p user |
35 | | - end |
36 | | -end |
37 | | -``` |
38 | | - |
39 | | -### Processing multiple result sets |
40 | | - |
41 | | -In order to send and receive multiple result sets, pass the `multi_statement` option when connecting. |
42 | | -`Trilogy#more_results_exist?` will return true if more results exist, false if no more results exist, or raise |
43 | | -an error if the respective query errored. `Trilogy#next_result` will retrieve the next result set, or return nil |
44 | | -if no more results exist. |
45 | | - |
46 | | -``` ruby |
47 | | -client = Trilogy.new(host: "127.0.0.1", port: 3306, username: "root", read_timeout: 2, multi_statement: true) |
48 | | - |
49 | | -results = [] |
50 | | -results << client.query("SELECT name FROM users WHERE id = 1; SELECT name FROM users WHERE id = 2") |
51 | | -results << client.next_result while client.more_results_exist? |
52 | | -``` |
53 | | - |
54 | | -## Building |
55 | | -You should use the rake commands to build/install/release the gem |
56 | | -For instance: |
57 | | -```shell |
58 | | -bundle exec rake build |
59 | | -``` |
60 | | - |
61 | | -## Contributing |
62 | | - |
63 | | -The official Ruby bindings are inside of the canonical trilogy repository itself. |
64 | | - |
65 | | -1. Fork it ( https://github.com/trilogy-libraries/trilogy/fork ) |
66 | | -2. Create your feature branch (`git checkout -b my-new-feature`) |
67 | | -3. Commit your changes (`git commit -am 'Add some feature'`) |
68 | | -4. Push to the branch (`git push origin my-new-feature`) |
69 | | -5. Create a new Pull Request |
70 | | - |
71 | | -## mysql2 gem compatibility |
72 | | - |
73 | | -The trilogy API was heavily inspired by the mysql2 gem but has a few notable |
74 | | -differences: |
75 | | - |
76 | | -* The `query_flags` don't inherit from the connection options hash. |
77 | | - This means that options like turning on/of casting will need to be set before |
78 | | - a query and not passed in at connect time. |
79 | | -* For performance reasons there is no `application_timezone` query option. If |
80 | | - casting is enabled and your database timezone is different than what the |
81 | | - application is expecting you'll need to do the conversion yourself later. |
82 | | -* While we still tag strings with the encoding configured on the field they came |
83 | | - from - for performance reasons no automatic transcoding into |
84 | | - `Encoding.default_internal` is done. Similarly to not automatically converting |
85 | | - Time objects from `database_timezone` into `application_timezone`, we leave |
86 | | - the transcoding step up to the caller. |
87 | | -* There is no `as` query option. Calling `Trilogy::Result#each` will yield an array |
88 | | - of row values. If you want a hash you should use `Trilogy::Result#each_hash`. |
| 12 | +Otherwise, this fork is identical to the [mainline Trilogy library](https://github.com/trilogy-libraries/trilogy). |
0 commit comments