Repository files navigation

A MySQL-Driver for Go'sdatabase/sql package

• Features
• Requirements
• Installation
• Usage
  • DSN (Data Source Name)
    • Password
    • Protocol
    • Address
    • Parameters
    • Examples
  • Connection pool and timeouts
  • context.Context Support
  • ColumnType Support
  • LOAD DATA LOCAL INFILE support
  • time.Time support
  • Unicode support
• Testing / Development
• License

• Lightweight andfast
• Native Go implementation. No C-bindings, just pure Go
• Connections over TCP/IPv4, TCP/IPv6, Unix domain sockets orcustom protocols
• Automatic handling of broken connections
• Automatic Connection Pooling(by database/sql package)
• Supports queries larger than 16MB
• Fullsql.RawBytes support.
• IntelligentLONG DATA handling in prepared statements
• SecureLOAD DATA LOCAL INFILE support with file allowlisting andio.Reader support
• Optionaltime.Time parsing
• Optional placeholder interpolation
• Supports zlib compression.

• Go 1.22 or higher. We aim to support the 3 latest versions of Go.
• MySQL (5.7+) and MariaDB (10.5+) are supported.
• TiDB is supported by PingCAP.
  • Do not ask questions about TiDB in our issue tracker or forum.
  • Document
  • Forum
• go-mysql would work with Percona Server, Google CloudSQL or Sphinx (2.2.3+).
  • Maintainers won't support them. Do not expect issues are investigated and resolved by maintainers.
  • Investigate issues yourself and please send a pull request to fix it.

Simple install the package to your$GOPATH with thego tool from shell:

go get -u github.com/go-sql-driver/mysql

Make sureGit is installed on your machine and in your system'sPATH.

Go MySQL Driver is an implementation of Go'sdatabase/sql/driver interface. You only need to import the driver and can use the fulldatabase/sql API then.

Usemysql asdriverName and a validDSN asdataSourceName:

import ("database/sql""time"_"github.com/go-sql-driver/mysql")// ...db,err:=sql.Open("mysql","user:password@/dbname")iferr!=nil {panic(err)}// See "Important settings" section.db.SetConnMaxLifetime(time.Minute*3)db.SetMaxOpenConns(10)db.SetMaxIdleConns(10)

Examples are available in our Wiki.

db.SetConnMaxLifetime() is required to ensure connections are closed by the driver safely before connection is closed by MySQL server, OS, or other middlewares. Since some middlewares close idle connections by 5 minutes, we recommend timeout shorter than 5 minutes. This setting helps load balancing and changing system variables too.

db.SetMaxOpenConns() is highly recommended to limit the number of connection used by the application. There is no recommended limit number because it depends on application and MySQL server.

db.SetMaxIdleConns() is recommended to be set same todb.SetMaxOpenConns(). When it is smaller thanSetMaxOpenConns(), connections can be opened and closed much more frequently than you expect. Idle connections can be closed by thedb.SetConnMaxLifetime(). If you want to close idle connections more rapidly, you can usedb.SetConnMaxIdleTime() since Go 1.15.

The Data Source Name has a common format, like e.g.PEAR DB uses it, but without type-prefix (optional parts marked by squared brackets):

[username[:password]@][protocol[(address)]]/dbname[?param1=value1&...&paramN=valueN]

A DSN in its fullest form:

username:password@protocol(address)/dbname?param=value

Except for the databasename, all values are optional. So the minimal DSN is:

/dbname

If you do not want to preselect a database, leavedbname empty:

/

This has the same effect as an empty DSN string:

dbname is escaped byPathEscape() since v1.8.0. If your database name isdbname/withslash, it becomes:

/dbname%2Fwithslash

Alternatively,Config.FormatDSN can be used to create a DSN string by filling a struct.

Passwords can consist of any character. Escaping isnot necessary.

Seenet.Dial for more information which networks are available.In general you should use a Unix domain socket if available and TCP otherwise for best performance.

For TCP and UDP networks, addresses have the formhost[:port].Ifport is omitted, the default port will be used.Ifhost is a literal IPv6 address, it must be enclosed in square brackets.The functionsnet.JoinHostPort andnet.SplitHostPort manipulate addresses in this form.

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.

Parameters are case-sensitive!

Notice that any oftrue,TRUE,True or1 is accepted to stand for a true boolean value. Not surprisingly, false can be specified as any of:false,FALSE,False or0.

Type:           boolValid Values:   true, falseDefault:        false

allowAllFiles=true disables the file allowlist forLOAD DATA LOCAL INFILE and allowsall files.Might be insecure!

Type:           boolValid Values:   true, falseDefault:        false

allowCleartextPasswords=true allows using thecleartext client side plugin if required by an account, such as one defined with thePAM authentication plugin. 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 includeTLS / SSL, IPsec, or a private network.

Type:           boolValid Values:   true, falseDefault:        false

allowFallbackToPlaintext=true acts like a--ssl-mode=PREFERRED MySQL client as described inCommand Options for Connecting to the Server

Type:           boolValid Values:   true, falseDefault:        true

allowNativePasswords=false disallows the usage of MySQL native password method.

Type:           boolValid Values:   true, falseDefault:        false

allowOldPasswords=true allows the usage of the insecure old password method. This should be avoided, but is necessary in some cases. See alsothe old_passwords wiki page.

Type:           stringValid Values:   <name>Default:        none

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 fails. This enables for example support forutf8mb4 (introduced in MySQL 5.5.3) with fallback toutf8 for older servers (charset=utf8mb4,utf8).

See alsoUnicode Support.

Type:           boolValid Values:   true, falseDefault:        true

On supported platforms connections retrieved from the connection pool are checked for liveness before using them. If the check fails, the respective connection is marked as bad and the query retried with another connection.checkConnLiveness=false disables this liveness check of connections.

Type:           stringValid Values:   <name>Default:        utf8mb4_general_ci

Sets the collation used for client-server interaction on connection. In contrast tocharset,collation does not issue additional queries. If the specified collation is unavailable on the target server, the connection will fail.

A list of valid charsets for a server is retrievable withSHOW COLLATION.

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.

Collations for charset "ucs2", "utf16", "utf16le", and "utf32" can not be used (ref).

See alsoUnicode Support.

Type:           boolValid Values:   true, falseDefault:        false

clientFoundRows=true causes an UPDATE to return the number of matching rows instead of the number of rows changed.

Type:           boolValid Values:   true, falseDefault:        false

WhencolumnsWithAlias is true, calls tosql.Rows.Columns() will return the table alias and the column name separated by a dot. For example:

SELECT u.id FROM users as u

will returnu.id instead of justid ifcolumnsWithAlias=true.

Type:           boolValid Values:   true, falseDefault:        false

Toggles zlib compression. false by default.

Type:           boolValid Values:   true, falseDefault:        false

IfinterpolateParams is true, placeholders (?) in calls todb.Query() anddb.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 withinterpolateParams=false.

This can not be used together with the multibyte encodings BIG5, CP932, GB2312, GBK or SJIS. These are rejected as they mayintroduce a SQL injection vulnerability!

Type:           stringValid Values:   <escaped name>Default:        UTC

Sets the location for time.Time values (when usingparseTime=true)."Local" sets the system's location. Seetime.LoadLocation for details.

Note that this sets the location for time.Time values but does not change MySQL'stime_zone setting. For that see thetime_zone system variable, which can also be set as a DSN parameter.

Please keep in mind, that param values must beurl.QueryEscape'ed. Alternatively you can manually replace the/ with%2F. For exampleUS/Pacific would beloc=US%2FPacific.

Type:           durationDefault:        0

Truncate time values to the specified duration. The value must be a decimal number with a unit suffix ("ms","s","m","h"), such as"30s","0.5m" or"1m30s".

Type:          decimal numberDefault:       64*1024*1024

Max packet size allowed in bytes. The default value is 64 MiB and should be adjusted to match the server settings.maxAllowedPacket=0 can be used to automatically fetch themax_allowed_packet variable from serveron every connection.

Type:           boolValid Values:   true, falseDefault:        false

Allow multiple statements in one query. This can be used to bach multiple queries. UseRows.NextResultSet() to get result of the second and subsequent queries.

WhenmultiStatements is used,? parameters must only be used in the first statement.interpolateParams can be used to avoid this limitation unless prepared statement is used explicitly.

It's possible to access the last inserted ID and number of affected rows for multiple statements by usingsql.Conn.Raw() and themysql.Result. For example:

conn,_:=db.Conn(ctx)conn.Raw(func(connany)error {ex:=conn.(driver.Execer)res,err:=ex.Exec(`  UPDATE point SET x = 1 WHERE y = 2;  UPDATE point SET x = 2 WHERE y = 3;  `,nil)// Both slices have 2 elements.log.Print(res.(mysql.Result).AllRowsAffected())log.Print(res.(mysql.Result).AllLastInsertIds())})

Type:           boolValid Values:   true, falseDefault:        false

parseTime=true changes the output type ofDATE andDATETIME values totime.Time instead of[]byte /stringThe date or datetime like0000-00-00 00:00:00 is converted into zero value oftime.Time.

Type:           durationDefault:        0

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".

Type:           boolValid Values:   true, falseDefault:        false

rejectReadOnly=true causes the driver to reject read-only connections. Thisis for a possible race condition during an automatic failover, where the mysqlclient gets connected to a read-only replica after the failover.

Note that this should be a fairly rare case, as an automatic failover normallyhappens when the primary is down, and the race condition shouldn't happenunless it comes back up online as soon as the failover is kicked off. On theother hand, when this happens, a MySQL application can get stuck on aread-only connection until restarted. It is however fairly easy to reproduce,for example, using a manual failover on AWS Aurora's MySQL-compatible cluster.

If you are not relying on read-only transactions to reject writes that aren'tsupposed to happen, setting this on some MySQL providers (such as AWS Aurora)is safer for failovers.

Note that ERROR 1290 can be returned for aread-only server and this option willcause a retry for that error. However the same error number is used for someother cases. You should ensure your application will never cause an ERROR 1290except forread-only mode when enabling this option.

Type:           stringValid Values:   <name>Default:        none

Server public keys can be registered withmysql.RegisterServerPubKey, which can then be used by the assigned name in the DSN.Public keys are used to transmit encrypted data, e.g. for authentication.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.

Type:           durationDefault:        OS default

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".

Type:           bool / stringValid Values:   true, false, skip-verify, preferred, <name>Default:        false

tls=true enables TLS / SSL encrypted connection to the server. Useskip-verify if you want to use a self-signed or invalid certificate (server side) or usepreferred to use TLS only when advertised by the server. This is similar toskip-verify, but additionally allows a fallback to a connection which is not encrypted. Neitherskip-verify norpreferred add any reliable security. You can use a custom TLS config after registering it withmysql.RegisterTLSConfig.

Type:           durationDefault:        0

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".

Type:           comma-delimited string of user-defined "key:value" pairsValid Values:   (<name1>:<value1>,<name2>:<value2>,...)Default:        none

Connection attributes are key-value pairs that application programs can pass to the server at connect time.

Any other parameters are interpreted as system variables:

• <boolean_var>=<value>:SET <boolean_var>=<value>
• <enum_var>=<value>:SET <enum_var>=<value>
• <string_var>=%27<value>%27:SET <string_var>='<value>'

Rules:

• The values for string variables must be quoted with'.
• The values must also beurl.QueryEscape'ed!(which implies values of string variables must be wrapped with%27).

Examples:

• autocommit=1:SET autocommit=1
• time_zone=%27Europe%2FParis%27:SET time_zone='Europe/Paris'
• transaction_isolation=%27REPEATABLE-READ%27:SET transaction_isolation='REPEATABLE-READ'

user@unix(/path/to/socket)/dbname

root:pw@unix(/tmp/mysql.sock)/myDatabase?loc=Local

user:password@tcp(localhost:5555)/dbname?tls=skip-verify&autocommit=true

Treat warnings as errors by setting the system variablesql_mode:

user:password@/dbname?sql_mode=TRADITIONAL

TCP via IPv6:

user:password@tcp([de:ad:be:ef::ca:fe]:80)/dbname?timeout=90s&collation=utf8mb4_unicode_ci

TCP on a remote host, e.g. Amazon RDS:

id:password@tcp(your-amazonaws-uri.com:3306)/dbname

Google Cloud SQL on App Engine:

user:password@unix(/cloudsql/project-id:region-name:instance-name)/dbname

TCP using default port (3306) on localhost:

user:password@tcp/dbname?charset=utf8mb4,utf8&sys_var=esc%40ped

Use the default protocol (tcp) and host (localhost:3306):

user:password@/dbname

No Database preselected:

user:password@/

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 thedatabase/sql documentation. The read, write, and dial timeouts for each individual connection are configured with the DSN parametersreadTimeout,writeTimeout, andtimeout, respectively.

This driver supports theColumnType interface introduced in Go 1.8, with the exception ofColumnType.Length(), which is currently not supported. All Unsigned database type names will be returnedUNSIGNED withINT,TINYINT,SMALLINT,MEDIUMINT,BIGINT.

Go 1.8 addeddatabase/sql support forcontext.Context. This driver supports query timeouts and cancellation via contexts.Seecontext support in the database/sql package for more details.

For this feature you need direct access to the package. Therefore you must change the import path (no_):

import"github.com/go-sql-driver/mysql"

Files must be explicitly allowed by registering them withmysql.RegisterLocalFile(filepath) (recommended) or the allowlist check must be deactivated by using the DSN parameterallowAllFiles=true (Might be insecure!).

To use aio.Reader a handler function must be registered withmysql.RegisterReaderHandler(name, handler) which returns aio.Reader orio.ReadCloser. The Reader is available with the filepathReader::<name> then. Choose different names for different handlers andDeregisterReaderHandler when you don't need it anymore.

See thegodoc of Go-MySQL-Driver for details.

The default internal output type of MySQLDATE andDATETIME values is[]byte which allows you to scan the value into a[]byte,string orsql.RawBytes variable in your program.

However, many want to scan MySQLDATE andDATETIME values intotime.Time variables, which is the logical equivalent in Go toDATE andDATETIME in MySQL. You can do that by changing the internal output type from[]byte totime.Time with the DSN parameterparseTime=true. You can set the defaulttime.Time location with theloc DSN parameter.

Caution: As of Go 1.1, this makestime.Time the only variable type you can scanDATE andDATETIME values into. This breaks for examplesql.RawBytes support.

Since version 1.5 Go-MySQL-Driver automatically uses the collation utf8mb4_general_ci by default.

Other charsets / collations can be set using thecharset orcollation DSN parameter.

• When only thecharset is specified, theSET NAMES <charset> query is sent and the server's default collation is used.
• When both thecharset andcollation are specified, theSET NAMES <charset> COLLATE <collation> query is sent.
• When only thecollation is specified, the collation is specified in the protocol handshake and theSET 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.

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

To run the driver tests you may need to adjust the configuration. See theTesting Wiki-Page for details.

Go-MySQL-Driver is not feature-complete yet. Your help is very appreciated.If you want to contribute, you can work on anopen issue or review apull request.

See theContribution Guidelines for details.

Go-MySQL-Driver is licensed under theMozilla Public License Version 2.0

Mozilla summarizes the license scope as follows:

MPL: The copyleft applies to any files containing MPLed code.

That means:

• You canuse theunchanged source code both in private and commercially.
• When distributing, youmust publish the source code of anychanged 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).
• Youneedn't publish the source code of your library as long as the files licensed under the MPL 2.0 areunchanged.

Please read theMPL 2.0 FAQ if you have further questions regarding the license.

You can read the full terms here:LICENSE.