Skip to content

Commit 88feb41

Browse files
committed
Update README.
Do not discourage `charset` parameter. It has own pros.
1 parent 632ec13 commit 88feb41

File tree

1 file changed

+9
-3
lines changed

1 file changed

+9
-3
lines changed

README.md

+9-3
Original file line numberDiff line numberDiff line change
@@ -202,8 +202,7 @@ Default: none
202202

203203
Sets the charset used for client-server interaction (`"SET NAMES <value>"`). If multiple charsets are set (separated by a comma), the following charset is used if setting the charset failes. This enables for example support for `utf8mb4` ([introduced in MySQL 5.5.3](http://dev.mysql.com/doc/refman/5.5/en/charset-unicode-utf8mb4.html)) with fallback to `utf8` for older servers (`charset=utf8mb4,utf8`).
204204

205-
Usage of the `charset` parameter is discouraged because it issues additional queries to the server.
206-
Unless you need the fallback behavior, please use `collation` instead.
205+
See also [Unicode Support](#unicode-support).
207206

208207
##### `checkConnLiveness`
209208

@@ -232,6 +231,7 @@ The default collation (`utf8mb4_general_ci`) is supported from MySQL 5.5. You s
232231

233232
Collations for charset "ucs2", "utf16", "utf16le", and "utf32" can not be used ([ref](https://dev.mysql.com/doc/refman/5.7/en/charset-connection.html#charset-connection-impermissible-client-charset)).
234233

234+
See also [Unicode Support](#unicode-support).
235235

236236
##### `clientFoundRows`
237237

@@ -513,7 +513,13 @@ Since version 1.5 Go-MySQL-Driver automatically uses the collation ` utf8mb4_gen
513513

514514
Other collations / charsets can be set using the [`collation`](#collation) DSN parameter.
515515

516-
Version 1.0 of the driver recommended adding `&charset=utf8` (alias for `SET NAMES utf8`) to the DSN to enable proper UTF-8 support. This is not necessary anymore. The [`collation`](#collation) parameter should be preferred to set another collation / charset than the default.
516+
Version 1.0 of the driver recommended adding `&charset=utf8` (alias for `SET NAMES utf8`) to the DSN to enable proper UTF-8 support. You can use [`collation`](#collation) parameter to set another collation / charset than the default.
517+
518+
Please correct next English.
519+
520+
- When only the `charset` is specified, the `SET NAMES <charset>` query is sent and the server's default collation is used.
521+
- When both the `charset` and `collation` are specified, the `SET NAMES <charset> COLLATE <collation>` query is sent.
522+
- When only the `collation` is specified, the collation is specified in the protocol handshake and the `SET NAMES` query is not sent. This can save one roundtrip, but note that the server may ignore the specified collation silently and use the server's default charset/collation instead.
517523

518524
See http://dev.mysql.com/doc/refman/8.0/en/charset-unicode.html for more details on MySQL's Unicode support.
519525

0 commit comments

Comments
 (0)