github.com/hellobchain/third_party@v0.0.0-20230331131523-deb0478a2e52/go-sql-driver/mysql/README.md (about) 1 # Go-MySQL-Driver 2 3 A MySQL-Driver for Go's [database/sql](https://golang.org/pkg/database/sql/) package 4 5  6 7 --------------------------------------- 8 * [Features](#features) 9 * [Requirements](#requirements) 10 * [Installation](#installation) 11 * [Usage](#usage) 12 * [DSN (Data Source Name)](#dsn-data-source-name) 13 * [Password](#password) 14 * [Protocol](#protocol) 15 * [Address](#address) 16 * [Parameters](#parameters) 17 * [Examples](#examples) 18 * [Connection pool and timeouts](#connection-pool-and-timeouts) 19 * [context.Context Support](#contextcontext-support) 20 * [ColumnType Support](#columntype-support) 21 * [LOAD DATA LOCAL INFILE support](#load-data-local-infile-support) 22 * [time.Time support](#timetime-support) 23 * [Unicode support](#unicode-support) 24 * [Testing / Development](#testing--development) 25 * [License](#license) 26 27 --------------------------------------- 28 29 ## Features 30 * Lightweight and [fast](https://github.com/go-sql-driver/sql-benchmark "golang MySQL-Driver performance") 31 * Native Go implementation. No C-bindings, just pure Go 32 * Connections over TCP/IPv4, TCP/IPv6, Unix domain sockets or [custom protocols](https://godoc.org/github.com/go-sql-driver/mysql#DialFunc) 33 * Automatic handling of broken connections 34 * Automatic Connection Pooling *(by database/sql package)* 35 * Supports queries larger than 16MB 36 * Full [`sql.RawBytes`](https://golang.org/pkg/database/sql/#RawBytes) support. 37 * Intelligent `LONG DATA` handling in prepared statements 38 * Secure `LOAD DATA LOCAL INFILE` support with file Whitelisting and `io.Reader` support 39 * Optional `time.Time` parsing 40 * Optional placeholder interpolation 41 42 ## Requirements 43 * Go 1.9 or higher. We aim to support the 3 latest versions of Go. 44 * MySQL (4.1+), MariaDB, Percona Server, Google CloudSQL or Sphinx (2.2.3+) 45 46 --------------------------------------- 47 48 ## Installation 49 Simple install the package to your [$GOPATH](https://github.com/golang/go/wiki/GOPATH "GOPATH") with the [go tool](https://golang.org/cmd/go/ "go command") from shell: 50 ```bash 51 $ go get -u github.com/go-sql-driver/mysql 52 ``` 53 Make sure [Git is installed](https://git-scm.com/downloads) on your machine and in your system's `PATH`. 54 55 ## Usage 56 _Go MySQL Driver_ is an implementation of Go's `database/sql/driver` interface. You only need to import the driver and can use the full [`database/sql`](https://golang.org/pkg/database/sql/) API then. 57 58 Use `mysql` as `driverName` and a valid [DSN](#dsn-data-source-name) as `dataSourceName`: 59 ```go 60 import "database/sql" 61 import _ "github.com/go-sql-driver/mysql" 62 63 db, err := sql.Open("mysql", "user:password@/dbname") 64 ``` 65 66 [Examples are available in our Wiki](https://github.com/go-sql-driver/mysql/wiki/Examples "Go-MySQL-Driver Examples"). 67 68 69 ### DSN (Data Source Name) 70 71 The Data Source Name has a common format, like e.g. [PEAR DB](http://pear.php.net/manual/en/package.database.db.intro-dsn.php) uses it, but without type-prefix (optional parts marked by squared brackets): 72 ``` 73 [username[:password]@][protocol[(address)]]/dbname[?param1=value1&...¶mN=valueN] 74 ``` 75 76 A DSN in its fullest form: 77 ``` 78 username:password@protocol(address)/dbname?param=value 79 ``` 80 81 Except for the databasename, all values are optional. So the minimal DSN is: 82 ``` 83 /dbname 84 ``` 85 86 If you do not want to preselect a database, leave `dbname` empty: 87 ``` 88 / 89 ``` 90 This has the same effect as an empty DSN string: 91 ``` 92 93 ``` 94 95 Alternatively, [Config.FormatDSN](https://godoc.org/github.com/go-sql-driver/mysql#Config.FormatDSN) can be used to create a DSN string by filling a struct. 96 97 #### Password 98 Passwords can consist of any character. Escaping is **not** necessary. 99 100 #### Protocol 101 See [net.Dial](https://golang.org/pkg/net/#Dial) for more information which networks are available. 102 In general you should use an Unix domain socket if available and TCP otherwise for best performance. 103 104 #### Address 105 For TCP and UDP networks, addresses have the form `host[:port]`. 106 If `port` is omitted, the default port will be used. 107 If `host` is a literal IPv6 address, it must be enclosed in square brackets. 108 The functions [net.JoinHostPort](https://golang.org/pkg/net/#JoinHostPort) and [net.SplitHostPort](https://golang.org/pkg/net/#SplitHostPort) manipulate addresses in this form. 109 110 For Unix domain sockets the address is the absolute path to the MySQL-Server-socket, e.g. `/var/run/mysqld/mysqld.sock` or `/tmp/mysql.sock`. 111 112 #### Parameters 113 *Parameters are case-sensitive!* 114 115 Notice that any of `true`, `TRUE`, `True` or `1` is accepted to stand for a true boolean value. Not surprisingly, false can be specified as any of: `false`, `FALSE`, `False` or `0`. 116 117 ##### `allowAllFiles` 118 119 ``` 120 Type: bool 121 Valid Values: true, false 122 Default: false 123 ``` 124 125 `allowAllFiles=true` disables the file Whitelist for `LOAD DATA LOCAL INFILE` and allows *all* files. 126 [*Might be insecure!*](http://dev.mysql.com/doc/refman/5.7/en/load-data-local.html) 127 128 ##### `allowCleartextPasswords` 129 130 ``` 131 Type: bool 132 Valid Values: true, false 133 Default: false 134 ``` 135 136 `allowCleartextPasswords=true` allows using the [cleartext client side plugin](http://dev.mysql.com/doc/en/cleartext-authentication-plugin.html) if required by an account, such as one defined with the [PAM authentication plugin](http://dev.mysql.com/doc/en/pam-authentication-plugin.html). Sending passwords in clear text may be a security problem in some configurations. To avoid problems if there is any possibility that the password would be intercepted, clients should connect to MySQL Server using a method that protects the password. Possibilities include [TLS / SSL](#tls), IPsec, or a private network. 137 138 ##### `allowNativePasswords` 139 140 ``` 141 Type: bool 142 Valid Values: true, false 143 Default: true 144 ``` 145 `allowNativePasswords=false` disallows the usage of MySQL native password method. 146 147 ##### `allowOldPasswords` 148 149 ``` 150 Type: bool 151 Valid Values: true, false 152 Default: false 153 ``` 154 `allowOldPasswords=true` allows the usage of the insecure old password method. This should be avoided, but is necessary in some cases. See also [the old_passwords wiki page](https://github.com/go-sql-driver/mysql/wiki/old_passwords). 155 156 ##### `charset` 157 158 ``` 159 Type: string 160 Valid Values: <name> 161 Default: none 162 ``` 163 164 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`). 165 166 Usage of the `charset` parameter is discouraged because it issues additional queries to the server. 167 Unless you need the fallback behavior, please use `collation` instead. 168 169 ##### `collation` 170 171 ``` 172 Type: string 173 Valid Values: <name> 174 Default: utf8mb4_general_ci 175 ``` 176 177 Sets the collation used for client-server interaction on connection. In contrast to `charset`, `collation` does not issue additional queries. If the specified collation is unavailable on the target server, the connection will fail. 178 179 A list of valid charsets for a server is retrievable with `SHOW COLLATION`. 180 181 The default collation (`utf8mb4_general_ci`) is supported from MySQL 5.5. You should use an older collation (e.g. `utf8_general_ci`) for older MySQL. 182 183 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)). 184 185 186 ##### `clientFoundRows` 187 188 ``` 189 Type: bool 190 Valid Values: true, false 191 Default: false 192 ``` 193 194 `clientFoundRows=true` causes an UPDATE to return the number of matching rows instead of the number of rows changed. 195 196 ##### `columnsWithAlias` 197 198 ``` 199 Type: bool 200 Valid Values: true, false 201 Default: false 202 ``` 203 204 When `columnsWithAlias` is true, calls to `sql.Rows.Columns()` will return the table alias and the column name separated by a dot. For example: 205 206 ``` 207 SELECT u.id FROM users as u 208 ``` 209 210 will return `u.id` instead of just `id` if `columnsWithAlias=true`. 211 212 ##### `interpolateParams` 213 214 ``` 215 Type: bool 216 Valid Values: true, false 217 Default: false 218 ``` 219 220 If `interpolateParams` is true, placeholders (`?`) in calls to `db.Query()` and `db.Exec()` are interpolated into a single query string with given parameters. This reduces the number of roundtrips, since the driver has to prepare a statement, execute it with given parameters and close the statement again with `interpolateParams=false`. 221 222 *This can not be used together with the multibyte encodings BIG5, CP932, GB2312, GBK or SJIS. These are blacklisted as they may [introduce a SQL injection vulnerability](http://stackoverflow.com/a/12118602/3430118)!* 223 224 ##### `loc` 225 226 ``` 227 Type: string 228 Valid Values: <escaped name> 229 Default: UTC 230 ``` 231 232 Sets the location for time.Time values (when using `parseTime=true`). *"Local"* sets the system's location. See [time.LoadLocation](https://golang.org/pkg/time/#LoadLocation) for details. 233 234 Note that this sets the location for time.Time values but does not change MySQL's [time_zone setting](https://dev.mysql.com/doc/refman/5.5/en/time-zone-support.html). For that see the [time_zone system variable](#system-variables), which can also be set as a DSN parameter. 235 236 Please keep in mind, that param values must be [url.QueryEscape](https://golang.org/pkg/net/url/#QueryEscape)'ed. Alternatively you can manually replace the `/` with `%2F`. For example `US/Pacific` would be `loc=US%2FPacific`. 237 238 ##### `maxAllowedPacket` 239 ``` 240 Type: decimal number 241 Default: 4194304 242 ``` 243 244 Max packet size allowed in bytes. The default value is 4 MiB and should be adjusted to match the server settings. `maxAllowedPacket=0` can be used to automatically fetch the `max_allowed_packet` variable from server *on every connection*. 245 246 ##### `multiStatements` 247 248 ``` 249 Type: bool 250 Valid Values: true, false 251 Default: false 252 ``` 253 254 Allow multiple statements in one query. While this allows batch queries, it also greatly increases the risk of SQL injections. Only the result of the first query is returned, all other results are silently discarded. 255 256 When `multiStatements` is used, `?` parameters must only be used in the first statement. 257 258 ##### `parseTime` 259 260 ``` 261 Type: bool 262 Valid Values: true, false 263 Default: false 264 ``` 265 266 `parseTime=true` changes the output type of `DATE` and `DATETIME` values to `time.Time` instead of `[]byte` / `string` 267 The date or datetime like `0000-00-00 00:00:00` is converted into zero value of `time.Time`. 268 269 270 ##### `readTimeout` 271 272 ``` 273 Type: duration 274 Default: 0 275 ``` 276 277 I/O read timeout. The value must be a decimal number with a unit suffix (*"ms"*, *"s"*, *"m"*, *"h"*), such as *"30s"*, *"0.5m"* or *"1m30s"*. 278 279 ##### `rejectReadOnly` 280 281 ``` 282 Type: bool 283 Valid Values: true, false 284 Default: false 285 ``` 286 287 288 `rejectReadOnly=true` causes the driver to reject read-only connections. This 289 is for a possible race condition during an automatic failover, where the mysql 290 client gets connected to a read-only replica after the failover. 291 292 Note that this should be a fairly rare case, as an automatic failover normally 293 happens when the primary is down, and the race condition shouldn't happen 294 unless it comes back up online as soon as the failover is kicked off. On the 295 other hand, when this happens, a MySQL application can get stuck on a 296 read-only connection until restarted. It is however fairly easy to reproduce, 297 for example, using a manual failover on AWS Aurora's MySQL-compatible cluster. 298 299 If you are not relying on read-only transactions to reject writes that aren't 300 supposed to happen, setting this on some MySQL providers (such as AWS Aurora) 301 is safer for failovers. 302 303 Note that ERROR 1290 can be returned for a `read-only` server and this option will 304 cause a retry for that error. However the same error number is used for some 305 other cases. You should ensure your application will never cause an ERROR 1290 306 except for `read-only` mode when enabling this option. 307 308 309 ##### `serverPubKey` 310 311 ``` 312 Type: string 313 Valid Values: <name> 314 Default: none 315 ``` 316 317 Server public keys can be registered with [`mysql.RegisterServerPubKey`](https://godoc.org/github.com/go-sql-driver/mysql#RegisterServerPubKey), which can then be used by the assigned name in the DSN. 318 Public keys are used to transmit encrypted data, e.g. for authentication. 319 If the server's public key is known, it should be set manually to avoid expensive and potentially insecure transmissions of the public key from the server to the client each time it is required. 320 321 322 ##### `timeout` 323 324 ``` 325 Type: duration 326 Default: OS default 327 ``` 328 329 Timeout for establishing connections, aka dial timeout. The value must be a decimal number with a unit suffix (*"ms"*, *"s"*, *"m"*, *"h"*), such as *"30s"*, *"0.5m"* or *"1m30s"*. 330 331 332 ##### `tls` 333 334 ``` 335 Type: bool / string 336 Valid Values: true, false, skip-verify, preferred, <name> 337 Default: false 338 ``` 339 340 `tls=true` enables TLS / SSL encrypted connection to the server. Use `skip-verify` if you want to use a self-signed or invalid certificate (server side) or use `preferred` to use TLS only when advertised by the server. This is similar to `skip-verify`, but additionally allows a fallback to a connection which is not encrypted. Neither `skip-verify` nor `preferred` add any reliable security. You can use a custom TLS config after registering it with [`mysql.RegisterTLSConfig`](https://godoc.org/github.com/go-sql-driver/mysql#RegisterTLSConfig). 341 342 343 ##### `writeTimeout` 344 345 ``` 346 Type: duration 347 Default: 0 348 ``` 349 350 I/O write timeout. The value must be a decimal number with a unit suffix (*"ms"*, *"s"*, *"m"*, *"h"*), such as *"30s"*, *"0.5m"* or *"1m30s"*. 351 352 353 ##### System Variables 354 355 Any other parameters are interpreted as system variables: 356 * `<boolean_var>=<value>`: `SET <boolean_var>=<value>` 357 * `<enum_var>=<value>`: `SET <enum_var>=<value>` 358 * `<string_var>=%27<value>%27`: `SET <string_var>='<value>'` 359 360 Rules: 361 * The values for string variables must be quoted with `'`. 362 * The values must also be [url.QueryEscape](http://golang.org/pkg/net/url/#QueryEscape)'ed! 363 (which implies values of string variables must be wrapped with `%27`). 364 365 Examples: 366 * `autocommit=1`: `SET autocommit=1` 367 * [`time_zone=%27Europe%2FParis%27`](https://dev.mysql.com/doc/refman/5.5/en/time-zone-support.html): `SET time_zone='Europe/Paris'` 368 * [`tx_isolation=%27REPEATABLE-READ%27`](https://dev.mysql.com/doc/refman/5.5/en/server-system-variables.html#sysvar_tx_isolation): `SET tx_isolation='REPEATABLE-READ'` 369 370 371 #### Examples 372 ``` 373 user@unix(/path/to/socket)/dbname 374 ``` 375 376 ``` 377 root:pw@unix(/tmp/mysql.sock)/myDatabase?loc=Local 378 ``` 379 380 ``` 381 user:password@tcp(localhost:5555)/dbname?tls=skip-verify&autocommit=true 382 ``` 383 384 Treat warnings as errors by setting the system variable [`sql_mode`](https://dev.mysql.com/doc/refman/5.7/en/sql-mode.html): 385 ``` 386 user:password@/dbname?sql_mode=TRADITIONAL 387 ``` 388 389 TCP via IPv6: 390 ``` 391 user:password@tcp([de:ad:be:ef::ca:fe]:80)/dbname?timeout=90s&collation=utf8mb4_unicode_ci 392 ``` 393 394 TCP on a remote host, e.g. Amazon RDS: 395 ``` 396 id:password@tcp(your-amazonaws-uri.com:3306)/dbname 397 ``` 398 399 Google Cloud SQL on App Engine (First Generation MySQL Server): 400 ``` 401 user@cloudsql(project-id:instance-name)/dbname 402 ``` 403 404 Google Cloud SQL on App Engine (Second Generation MySQL Server): 405 ``` 406 user@cloudsql(project-id:regionname:instance-name)/dbname 407 ``` 408 409 TCP using default port (3306) on localhost: 410 ``` 411 user:password@tcp/dbname?charset=utf8mb4,utf8&sys_var=esc%40ped 412 ``` 413 414 Use the default protocol (tcp) and host (localhost:3306): 415 ``` 416 user:password@/dbname 417 ``` 418 419 No Database preselected: 420 ``` 421 user:password@/ 422 ``` 423 424 425 ### Connection pool and timeouts 426 The connection pool is managed by Go's database/sql package. For details on how to configure the size of the pool and how long connections stay in the pool see `*DB.SetMaxOpenConns`, `*DB.SetMaxIdleConns`, and `*DB.SetConnMaxLifetime` in the [database/sql documentation](https://golang.org/pkg/database/sql/). The read, write, and dial timeouts for each individual connection are configured with the DSN parameters [`readTimeout`](#readtimeout), [`writeTimeout`](#writetimeout), and [`timeout`](#timeout), respectively. 427 428 ## `ColumnType` Support 429 This driver supports the [`ColumnType` interface](https://golang.org/pkg/database/sql/#ColumnType) introduced in Go 1.8, with the exception of [`ColumnType.Length()`](https://golang.org/pkg/database/sql/#ColumnType.Length), which is currently not supported. 430 431 ## `context.Context` Support 432 Go 1.8 added `database/sql` support for `context.Context`. This driver supports query timeouts and cancellation via contexts. 433 See [context support in the database/sql package](https://golang.org/doc/go1.8#database_sql) for more details. 434 435 436 ### `LOAD DATA LOCAL INFILE` support 437 For this feature you need direct access to the package. Therefore you must change the import path (no `_`): 438 ```go 439 import "github.com/go-sql-driver/mysql" 440 ``` 441 442 Files must be whitelisted by registering them with `mysql.RegisterLocalFile(filepath)` (recommended) or the Whitelist check must be deactivated by using the DSN parameter `allowAllFiles=true` ([*Might be insecure!*](http://dev.mysql.com/doc/refman/5.7/en/load-data-local.html)). 443 444 To use a `io.Reader` a handler function must be registered with `mysql.RegisterReaderHandler(name, handler)` which returns a `io.Reader` or `io.ReadCloser`. The Reader is available with the filepath `Reader::<name>` then. Choose different names for different handlers and `DeregisterReaderHandler` when you don't need it anymore. 445 446 See the [godoc of Go-MySQL-Driver](https://godoc.org/github.com/go-sql-driver/mysql "golang mysql driver documentation") for details. 447 448 449 ### `time.Time` support 450 The default internal output type of MySQL `DATE` and `DATETIME` values is `[]byte` which allows you to scan the value into a `[]byte`, `string` or `sql.RawBytes` variable in your program. 451 452 However, many want to scan MySQL `DATE` and `DATETIME` values into `time.Time` variables, which is the logical equivalent in Go to `DATE` and `DATETIME` in MySQL. You can do that by changing the internal output type from `[]byte` to `time.Time` with the DSN parameter `parseTime=true`. You can set the default [`time.Time` location](https://golang.org/pkg/time/#Location) with the `loc` DSN parameter. 453 454 **Caution:** As of Go 1.1, this makes `time.Time` the only variable type you can scan `DATE` and `DATETIME` values into. This breaks for example [`sql.RawBytes` support](https://github.com/go-sql-driver/mysql/wiki/Examples#rawbytes). 455 456 Alternatively you can use the [`NullTime`](https://godoc.org/github.com/go-sql-driver/mysql#NullTime) type as the scan destination, which works with both `time.Time` and `string` / `[]byte`. 457 458 459 ### Unicode support 460 Since version 1.1 Go-MySQL-Driver automatically uses the collation `utf8_general_ci` by default. 461 462 Other collations / charsets can be set using the [`collation`](#collation) DSN parameter. 463 464 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. 465 466 See http://dev.mysql.com/doc/refman/5.7/en/charset-unicode.html for more details on MySQL's Unicode support. 467 468 ## Testing / Development 469 To run the driver tests you may need to adjust the configuration. See the [Testing Wiki-Page](https://github.com/go-sql-driver/mysql/wiki/Testing "Testing") for details. 470 471 Go-MySQL-Driver is not feature-complete yet. Your help is very appreciated. 472 If you want to contribute, you can work on an [open issue](https://github.com/go-sql-driver/mysql/issues?state=open) or review a [pull request](https://github.com/go-sql-driver/mysql/pulls). 473 474 See the [Contribution Guidelines](https://github.com/go-sql-driver/mysql/blob/master/CONTRIBUTING.md) for details. 475 476 --------------------------------------- 477 478 ## License 479 Go-MySQL-Driver is licensed under the [Mozilla Public License Version 2.0](https://raw.github.com/go-sql-driver/mysql/master/LICENSE) 480 481 Mozilla summarizes the license scope as follows: 482 > MPL: The copyleft applies to any files containing MPLed code. 483 484 485 That means: 486 * You can **use** the **unchanged** source code both in private and commercially. 487 * When distributing, you **must publish** the source code of any **changed files** licensed under the MPL 2.0 under a) the MPL 2.0 itself or b) a compatible license (e.g. GPL 3.0 or Apache License 2.0). 488 * You **needn't publish** the source code of your library as long as the files licensed under the MPL 2.0 are **unchanged**. 489 490 Please read the [MPL 2.0 FAQ](https://www.mozilla.org/en-US/MPL/2.0/FAQ/) if you have further questions regarding the license. 491 492 You can read the full terms here: [LICENSE](https://raw.github.com/go-sql-driver/mysql/master/LICENSE). 493 494  495