vendor/github.com/go-sql-driver/mysql/README.md

   1 # Go-MySQL-Driver
   2
   3 A MySQL-Driver for Go's [database/sql](https://golang.org/pkg/database/sql/) package
   4
   5 ![Go-MySQL-Driver logo](https://raw.github.com/wiki/go-sql-driver/mysql/gomysql_m.png "Golang Gopher holding the MySQL Dolphin")
   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.8 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&...&paramN=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:        utf8_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 ##### `clientFoundRows`
 182
 183 ```
 184 Type:           bool
 185 Valid Values:   true, false
 186 Default:        false
 187 ```
 188
 189 `clientFoundRows=true` causes an UPDATE to return the number of matching rows instead of the number of rows changed.
 190
 191 ##### `columnsWithAlias`
 192
 193 ```
 194 Type:           bool
 195 Valid Values:   true, false
 196 Default:        false
 197 ```
 198
 199 When `columnsWithAlias` is true, calls to `sql.Rows.Columns()` will return the table alias and the column name separated by a dot. For example:
 200
 201 ```
 202 SELECT u.id FROM users as u
 203 ```
 204
 205 will return `u.id` instead of just `id` if `columnsWithAlias=true`.
 206
 207 ##### `interpolateParams`
 208
 209 ```
 210 Type:           bool
 211 Valid Values:   true, false
 212 Default:        false
 213 ```
 214
 215 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`.
 216
 217 *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)!*
 218
 219 ##### `loc`
 220
 221 ```
 222 Type:           string
 223 Valid Values:   <escaped name>
 224 Default:        UTC
 225 ```
 226
 227 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.
 228
 229 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.
 230
 231 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`.
 232
 233 ##### `maxAllowedPacket`
 234 ```
 235 Type:          decimal number
 236 Default:       4194304
 237 ```
 238
 239 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*.
 240
 241 ##### `multiStatements`
 242
 243 ```
 244 Type:           bool
 245 Valid Values:   true, false
 246 Default:        false
 247 ```
 248
 249 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.
 250
 251 When `multiStatements` is used, `?` parameters must only be used in the first statement.
 252
 253 ##### `parseTime`
 254
 255 ```
 256 Type:           bool
 257 Valid Values:   true, false
 258 Default:        false
 259 ```
 260
 261 `parseTime=true` changes the output type of `DATE` and `DATETIME` values to `time.Time` instead of `[]byte` / `string`
 262 The date or datetime like `0000-00-00 00:00:00` is converted into zero value of `time.Time`.
 263
 264
 265 ##### `readTimeout`
 266
 267 ```
 268 Type:           duration
 269 Default:        0
 270 ```
 271
 272 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"*.
 273
 274 ##### `rejectReadOnly`
 275
 276 ```
 277 Type:           bool
 278 Valid Values:   true, false
 279 Default:        false
 280 ```
 281
 282
 283 `rejectReadOnly=true` causes the driver to reject read-only connections. This
 284 is for a possible race condition during an automatic failover, where the mysql
 285 client gets connected to a read-only replica after the failover.
 286
 287 Note that this should be a fairly rare case, as an automatic failover normally
 288 happens when the primary is down, and the race condition shouldn't happen
 289 unless it comes back up online as soon as the failover is kicked off. On the
 290 other hand, when this happens, a MySQL application can get stuck on a
 291 read-only connection until restarted. It is however fairly easy to reproduce,
 292 for example, using a manual failover on AWS Aurora's MySQL-compatible cluster.
 293
 294 If you are not relying on read-only transactions to reject writes that aren't
 295 supposed to happen, setting this on some MySQL providers (such as AWS Aurora)
 296 is safer for failovers.
 297
 298 Note that ERROR 1290 can be returned for a `read-only` server and this option will
 299 cause a retry for that error. However the same error number is used for some
 300 other cases. You should ensure your application will never cause an ERROR 1290
 301 except for `read-only` mode when enabling this option.
 302
 303
 304 ##### `serverPubKey`
 305
 306 ```
 307 Type:           string
 308 Valid Values:   <name>
 309 Default:        none
 310 ```
 311
 312 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.
 313 Public keys are used to transmit encrypted data, e.g. for authentication.
 314 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.
 315
 316
 317 ##### `timeout`
 318
 319 ```
 320 Type:           duration
 321 Default:        OS default
 322 ```
 323
 324 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"*.
 325
 326
 327 ##### `tls`
 328
 329 ```
 330 Type:           bool / string
 331 Valid Values:   true, false, skip-verify, <name>
 332 Default:        false
 333 ```
 334
 335 `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). Use a custom value registered with [`mysql.RegisterTLSConfig`](https://godoc.org/github.com/go-sql-driver/mysql#RegisterTLSConfig).
 336
 337
 338 ##### `writeTimeout`
 339
 340 ```
 341 Type:           duration
 342 Default:        0
 343 ```
 344
 345 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"*.
 346
 347
 348 ##### System Variables
 349
 350 Any other parameters are interpreted as system variables:
 351   * `<boolean_var>=<value>`: `SET <boolean_var>=<value>`
 352   * `<enum_var>=<value>`: `SET <enum_var>=<value>`
 353   * `<string_var>=%27<value>%27`: `SET <string_var>='<value>'`
 354
 355 Rules:
 356 * The values for string variables must be quoted with `'`.
 357 * The values must also be [url.QueryEscape](http://golang.org/pkg/net/url/#QueryEscape)'ed!
 358  (which implies values of string variables must be wrapped with `%27`).
 359
 360 Examples:
 361   * `autocommit=1`: `SET autocommit=1`
 362   * [`time_zone=%27Europe%2FParis%27`](https://dev.mysql.com/doc/refman/5.5/en/time-zone-support.html): `SET time_zone='Europe/Paris'`
 363   * [`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'`
 364
 365
 366 #### Examples
 367 ```
 368 user@unix(/path/to/socket)/dbname
 369 ```
 370
 371 ```
 372 root:pw@unix(/tmp/mysql.sock)/myDatabase?loc=Local
 373 ```
 374
 375 ```
 376 user:password@tcp(localhost:5555)/dbname?tls=skip-verify&autocommit=true
 377 ```
 378
 379 Treat warnings as errors by setting the system variable [`sql_mode`](https://dev.mysql.com/doc/refman/5.7/en/sql-mode.html):
 380 ```
 381 user:password@/dbname?sql_mode=TRADITIONAL
 382 ```
 383
 384 TCP via IPv6:
 385 ```
 386 user:password@tcp([de:ad:be:ef::ca:fe]:80)/dbname?timeout=90s&collation=utf8mb4_unicode_ci
 387 ```
 388
 389 TCP on a remote host, e.g. Amazon RDS:
 390 ```
 391 id:password@tcp(your-amazonaws-uri.com:3306)/dbname
 392 ```
 393
 394 Google Cloud SQL on App Engine (First Generation MySQL Server):
 395 ```
 396 user@cloudsql(project-id:instance-name)/dbname
 397 ```
 398
 399 Google Cloud SQL on App Engine (Second Generation MySQL Server):
 400 ```
 401 user@cloudsql(project-id:regionname:instance-name)/dbname
 402 ```
 403
 404 TCP using default port (3306) on localhost:
 405 ```
 406 user:password@tcp/dbname?charset=utf8mb4,utf8&sys_var=esc%40ped
 407 ```
 408
 409 Use the default protocol (tcp) and host (localhost:3306):
 410 ```
 411 user:password@/dbname
 412 ```
 413
 414 No Database preselected:
 415 ```
 416 user:password@/
 417 ```
 418
 419
 420 ### Connection pool and timeouts
 421 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.
 422
 423 ## `ColumnType` Support
 424 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.
 425
 426 ## `context.Context` Support
 427 Go 1.8 added `database/sql` support for `context.Context`. This driver supports query timeouts and cancellation via contexts.
 428 See [context support in the database/sql package](https://golang.org/doc/go1.8#database_sql) for more details.
 429
 430
 431 ### `LOAD DATA LOCAL INFILE` support
 432 For this feature you need direct access to the package. Therefore you must change the import path (no `_`):
 433 ```go
 434 import "github.com/go-sql-driver/mysql"
 435 ```
 436
 437 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)).
 438
 439 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.
 440
 441 See the [godoc of Go-MySQL-Driver](https://godoc.org/github.com/go-sql-driver/mysql "golang mysql driver documentation") for details.
 442
 443
 444 ### `time.Time` support
 445 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.
 446
 447 However, many want to scan MySQL `DATE` and `DATETIME` values into `time.Time` variables, which is the logical opposite 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.
 448
 449 **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).
 450
 451 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`.
 452
 453
 454 ### Unicode support
 455 Since version 1.1 Go-MySQL-Driver automatically uses the collation `utf8_general_ci` by default.
 456
 457 Other collations / charsets can be set using the [`collation`](#collation) DSN parameter.
 458
 459 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.
 460
 461 See http://dev.mysql.com/doc/refman/5.7/en/charset-unicode.html for more details on MySQL's Unicode support.
 462
 463 ## Testing / Development
 464 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.
 465
 466 Go-MySQL-Driver is not feature-complete yet. Your help is very appreciated.
 467 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).
 468
 469 See the [Contribution Guidelines](https://github.com/go-sql-driver/mysql/blob/master/CONTRIBUTING.md) for details.
 470
 471 ---------------------------------------
 472
 473 ## License
 474 Go-MySQL-Driver is licensed under the [Mozilla Public License Version 2.0](https://raw.github.com/go-sql-driver/mysql/master/LICENSE)
 475
 476 Mozilla summarizes the license scope as follows:
 477 > MPL: The copyleft applies to any files containing MPLed code.
 478
 479
 480 That means:
 481   * You can **use** the **unchanged** source code both in private and commercially.
 482   * 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).
 483   * You **needn't publish** the source code of your library as long as the files licensed under the MPL 2.0 are **unchanged**.
 484
 485 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.
 486
 487 You can read the full terms here: [LICENSE](https://raw.github.com/go-sql-driver/mysql/master/LICENSE).
 488
 489 ![Go Gopher and MySQL Dolphin](https://raw.github.com/wiki/go-sql-driver/mysql/go-mysql-driver_m.jpg "Golang Gopher transporting the MySQL Dolphin in a wheelbarrow")
 490