Skip to content

Commit 06274b4

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

File tree

1 file changed

+6
-4
lines changed

1 file changed

+6
-4
lines changed

Diff for: README.md

+6-4
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

@@ -511,9 +511,11 @@ However, many want to scan MySQL `DATE` and `DATETIME` values into `time.Time` v
511511
### Unicode support
512512
Since version 1.5 Go-MySQL-Driver automatically uses the collation ` utf8mb4_general_ci` by default.
513513

514-
Other collations / charsets can be set using the [`collation`](#collation) DSN parameter.
514+
Other charsets / collations can be set using the [`charset`](#charset) or [`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+
- When only the `charset` is specified, the `SET NAMES <charset>` query is sent and the server's default collation is used.
517+
- When both the `charset` and `collation` are specified, the `SET NAMES <charset> COLLATE <collation>` query is sent.
518+
- 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.
517519

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

0 commit comments

Comments
 (0)