github.com/insionng/yougam@v0.0.0-20170714101924-2bc18d833463/libraries/go-sql-driver/mysql/README.md (about) 1 # Go-MySQL-Driver 2 3 A MySQL-Driver for Go's [database/sql](http://golang.org/pkg/database/sql) package 4 5  6 7 **Latest stable Release:** [Version 1.2 (June 03, 2014)](https://github.com/go-sql-driver/mysql/releases) 8 9 [](https://travis-ci.org/go-sql-driver/mysql) 10 11 --------------------------------------- 12 * [Features](#features) 13 * [Requirements](#requirements) 14 * [Installation](#installation) 15 * [Usage](#usage) 16 * [DSN (Data Source Name)](#dsn-data-source-name) 17 * [Password](#password) 18 * [Protocol](#protocol) 19 * [Address](#address) 20 * [Parameters](#parameters) 21 * [Examples](#examples) 22 * [LOAD DATA LOCAL INFILE support](#load-data-local-infile-support) 23 * [time.Time support](#timetime-support) 24 * [Unicode support](#unicode-support) 25 * [Testing / Development](#testing--development) 26 * [License](#license) 27 28 --------------------------------------- 29 30 ## Features 31 * Lightweight and [fast](https://github.com/go-sql-driver/sql-benchmark "golang MySQL-Driver performance") 32 * Native Go implementation. No C-bindings, just pure Go 33 * Connections over TCP/IPv4, TCP/IPv6, Unix domain sockets or [custom protocols](http://godoc.org/github.com/go-sql-driver/mysql#DialFunc) 34 * Automatic handling of broken connections 35 * Automatic Connection Pooling *(by database/sql package)* 36 * Supports queries larger than 16MB 37 * Full [`sql.RawBytes`](http://golang.org/pkg/database/sql/#RawBytes) support. 38 * Intelligent `LONG DATA` handling in prepared statements 39 * Secure `LOAD DATA LOCAL INFILE` support with file Whitelisting and `io.Reader` support 40 * Optional `time.Time` parsing 41 * Optional placeholder interpolation 42 43 ## Requirements 44 * Go 1.2 or higher 45 * MySQL (4.1+), MariaDB, Percona Server, Google CloudSQL or Sphinx (2.2.3+) 46 47 --------------------------------------- 48 49 ## Installation 50 Simple install the package to your [$GOPATH](http://code.google.com/p/go-wiki/wiki/GOPATH "GOPATH") with the [go tool](http://golang.org/cmd/go/ "go command") from shell: 51 ```bash 52 $ go get github.com/go-sql-driver/mysql 53 ``` 54 Make sure [Git is installed](http://git-scm.com/downloads) on your machine and in your system's `PATH`. 55 56 ## Usage 57 _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`](http://golang.org/pkg/database/sql) API then. 58 59 Use `mysql` as `driverName` and a valid [DSN](#dsn-data-source-name) as `dataSourceName`: 60 ```go 61 import "database/sql" 62 import _ "github.com/go-sql-driver/mysql" 63 64 db, err := sql.Open("mysql", "user:password@/dbname") 65 ``` 66 67 [Examples are available in our Wiki](https://github.com/go-sql-driver/mysql/wiki/Examples "Go-MySQL-Driver Examples"). 68 69 70 ### DSN (Data Source Name) 71 72 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): 73 ``` 74 [username[:password]@][protocol[(address)]]/dbname[?param1=value1&...¶mN=valueN] 75 ``` 76 77 A DSN in its fullest form: 78 ``` 79 username:password@protocol(address)/dbname?param=value 80 ``` 81 82 Except for the databasename, all values are optional. So the minimal DSN is: 83 ``` 84 /dbname 85 ``` 86 87 If you do not want to preselect a database, leave `dbname` empty: 88 ``` 89 / 90 ``` 91 This has the same effect as an empty DSN string: 92 ``` 93 94 ``` 95 96 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. 97 98 #### Password 99 Passwords can consist of any character. Escaping is **not** necessary. 100 101 #### Protocol 102 See [net.Dial](http://golang.org/pkg/net/#Dial) for more information which networks are available. 103 In general you should use an Unix domain socket if available and TCP otherwise for best performance. 104 105 #### Address 106 For TCP and UDP networks, addresses have the form `host:port`. 107 If `host` is a literal IPv6 address, it must be enclosed in square brackets. 108 The functions [net.JoinHostPort](http://golang.org/pkg/net/#JoinHostPort) and [net.SplitHostPort](http://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 ##### `allowOldPasswords` 139 140 ``` 141 Type: bool 142 Valid Values: true, false 143 Default: false 144 ``` 145 `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). 146 147 ##### `charset` 148 149 ``` 150 Type: string 151 Valid Values: <name> 152 Default: none 153 ``` 154 155 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`). 156 157 Usage of the `charset` parameter is discouraged because it issues additional queries to the server. 158 Unless you need the fallback behavior, please use `collation` instead. 159 160 ##### `collation` 161 162 ``` 163 Type: string 164 Valid Values: <name> 165 Default: utf8_general_ci 166 ``` 167 168 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. 169 170 A list of valid charsets for a server is retrievable with `SHOW COLLATION`. 171 172 ##### `clientFoundRows` 173 174 ``` 175 Type: bool 176 Valid Values: true, false 177 Default: false 178 ``` 179 180 `clientFoundRows=true` causes an UPDATE to return the number of matching rows instead of the number of rows changed. 181 182 ##### `columnsWithAlias` 183 184 ``` 185 Type: bool 186 Valid Values: true, false 187 Default: false 188 ``` 189 190 When `columnsWithAlias` is true, calls to `sql.Rows.Columns()` will return the table alias and the column name separated by a dot. For example: 191 192 ``` 193 SELECT u.id FROM users as u 194 ``` 195 196 will return `u.id` instead of just `id` if `columnsWithAlias=true`. 197 198 ##### `interpolateParams` 199 200 ``` 201 Type: bool 202 Valid Values: true, false 203 Default: false 204 ``` 205 206 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`. 207 208 *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)!* 209 210 ##### `loc` 211 212 ``` 213 Type: string 214 Valid Values: <escaped name> 215 Default: UTC 216 ``` 217 218 Sets the location for time.Time values (when using `parseTime=true`). *"Local"* sets the system's location. See [time.LoadLocation](http://golang.org/pkg/time/#LoadLocation) for details. 219 220 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. 221 222 Please keep in mind, that param values must be [url.QueryEscape](http://golang.org/pkg/net/url/#QueryEscape)'ed. Alternatively you can manually replace the `/` with `%2F`. For example `US/Pacific` would be `loc=US%2FPacific`. 223 224 ##### `multiStatements` 225 226 ``` 227 Type: bool 228 Valid Values: true, false 229 Default: false 230 ``` 231 232 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. 233 234 When `multiStatements` is used, `?` parameters must only be used in the first statement. 235 236 237 ##### `parseTime` 238 239 ``` 240 Type: bool 241 Valid Values: true, false 242 Default: false 243 ``` 244 245 `parseTime=true` changes the output type of `DATE` and `DATETIME` values to `time.Time` instead of `[]byte` / `string` 246 247 248 ##### `readTimeout` 249 250 ``` 251 Type: decimal number 252 Default: 0 253 ``` 254 255 I/O read timeout. The value must be a decimal number with an unit suffix ( *"ms"*, *"s"*, *"m"*, *"h"* ), such as *"30s"*, *"0.5m"* or *"1m30s"*. 256 257 258 ##### `strict` 259 260 ``` 261 Type: bool 262 Valid Values: true, false 263 Default: false 264 ``` 265 266 `strict=true` enables the strict mode in which MySQL warnings are treated as errors. 267 268 By default MySQL also treats notes as warnings. Use [`sql_notes=false`](http://dev.mysql.com/doc/refman/5.7/en/server-system-variables.html#sysvar_sql_notes) to ignore notes. See the [examples](#examples) for an DSN example. 269 270 271 ##### `timeout` 272 273 ``` 274 Type: decimal number 275 Default: OS default 276 ``` 277 278 *Driver* side connection timeout. The value must be a decimal number with an unit suffix ( *"ms"*, *"s"*, *"m"*, *"h"* ), such as *"30s"*, *"0.5m"* or *"1m30s"*. To set a server side timeout, use the parameter [`wait_timeout`](http://dev.mysql.com/doc/refman/5.6/en/server-system-variables.html#sysvar_wait_timeout). 279 280 281 ##### `tls` 282 283 ``` 284 Type: bool / string 285 Valid Values: true, false, skip-verify, <name> 286 Default: false 287 ``` 288 289 `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`](http://godoc.org/github.com/go-sql-driver/mysql#RegisterTLSConfig). 290 291 292 ##### `writeTimeout` 293 294 ``` 295 Type: decimal number 296 Default: 0 297 ``` 298 299 I/O write timeout. The value must be a decimal number with an unit suffix ( *"ms"*, *"s"*, *"m"*, *"h"* ), such as *"30s"*, *"0.5m"* or *"1m30s"*. 300 301 302 ##### System Variables 303 304 All other parameters are interpreted as system variables: 305 * `autocommit`: `"SET autocommit=<value>"` 306 * [`time_zone`](https://dev.mysql.com/doc/refman/5.5/en/time-zone-support.html): `"SET time_zone=<value>"` 307 * [`tx_isolation`](https://dev.mysql.com/doc/refman/5.5/en/server-system-variables.html#sysvar_tx_isolation): `"SET tx_isolation=<value>"` 308 * `param`: `"SET <param>=<value>"` 309 310 *The values must be [url.QueryEscape](http://golang.org/pkg/net/url/#QueryEscape)'ed!* 311 312 #### Examples 313 ``` 314 user@unix(/path/to/socket)/dbname 315 ``` 316 317 ``` 318 root:pw@unix(/tmp/mysql.sock)/myDatabase?loc=Local 319 ``` 320 321 ``` 322 user:password@tcp(localhost:5555)/dbname?tls=skip-verify&autocommit=true 323 ``` 324 325 Use the [strict mode](#strict) but ignore notes: 326 ``` 327 user:password@/dbname?strict=true&sql_notes=false 328 ``` 329 330 TCP via IPv6: 331 ``` 332 user:password@tcp([de:ad:be:ef::ca:fe]:80)/dbname?timeout=90s&collation=utf8mb4_unicode_ci 333 ``` 334 335 TCP on a remote host, e.g. Amazon RDS: 336 ``` 337 id:password@tcp(your-amazonaws-uri.com:3306)/dbname 338 ``` 339 340 Google Cloud SQL on App Engine: 341 ``` 342 user@cloudsql(project-id:instance-name)/dbname 343 ``` 344 345 TCP using default port (3306) on localhost: 346 ``` 347 user:password@tcp/dbname?charset=utf8mb4,utf8&sys_var=esc%40ped 348 ``` 349 350 Use the default protocol (tcp) and host (localhost:3306): 351 ``` 352 user:password@/dbname 353 ``` 354 355 No Database preselected: 356 ``` 357 user:password@/ 358 ``` 359 360 ### `LOAD DATA LOCAL INFILE` support 361 For this feature you need direct access to the package. Therefore you must change the import path (no `_`): 362 ```go 363 import "github.com/go-sql-driver/mysql" 364 ``` 365 366 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)). 367 368 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. 369 370 See the [godoc of Go-MySQL-Driver](http://godoc.org/github.com/go-sql-driver/mysql "golang mysql driver documentation") for details. 371 372 373 ### `time.Time` support 374 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 programm. 375 376 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](http://golang.org/pkg/time/#Location) with the `loc` DSN parameter. 377 378 **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). 379 380 Alternatively you can use the [`NullTime`](http://godoc.org/github.com/go-sql-driver/mysql#NullTime) type as the scan destination, which works with both `time.Time` and `string` / `[]byte`. 381 382 383 ### Unicode support 384 Since version 1.1 Go-MySQL-Driver automatically uses the collation `utf8_general_ci` by default. 385 386 Other collations / charsets can be set using the [`collation`](#collation) DSN parameter. 387 388 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. 389 390 See http://dev.mysql.com/doc/refman/5.7/en/charset-unicode.html for more details on MySQL's Unicode support. 391 392 393 ## Testing / Development 394 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. 395 396 Go-MySQL-Driver is not feature-complete yet. Your help is very appreciated. 397 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). 398 399 See the [Contribution Guidelines](https://github.com/go-sql-driver/mysql/blob/master/CONTRIBUTING.md) for details. 400 401 --------------------------------------- 402 403 ## License 404 Go-MySQL-Driver is licensed under the [Mozilla Public License Version 2.0](https://raw.github.com/go-sql-driver/mysql/master/LICENSE) 405 406 Mozilla summarizes the license scope as follows: 407 > MPL: The copyleft applies to any files containing MPLed code. 408 409 410 That means: 411 * You can **use** the **unchanged** source code both in private and commercially 412 * 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) 413 * You **needn't publish** the source code of your library as long as the files licensed under the MPL 2.0 are **unchanged** 414 415 Please read the [MPL 2.0 FAQ](http://www.mozilla.org/MPL/2.0/FAQ.html) if you have further questions regarding the license. 416 417 You can read the full terms here: [LICENSE](https://raw.github.com/go-sql-driver/mysql/master/LICENSE) 418 419  420