mysql

by go-sql-driver

go-sql-driver / mysql

Go MySQL Driver is a MySQL driver for Go's (golang) database/sql package

10.1K Stars 1.8K Forks Last release: 10 months ago (v1.5.0) Mozilla Public License 2.0 814 Commits 17 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Go-MySQL-Driver

A MySQL-Driver for Go's database/sql package

Go-MySQL-Driver logo



Features

  • Lightweight and fast
  • Native Go implementation. No C-bindings, just pure Go
  • Connections over TCP/IPv4, TCP/IPv6, Unix domain sockets or custom protocols
  • Automatic handling of broken connections
  • Automatic Connection Pooling (by database/sql package)
  • Supports queries larger than 16MB
  • Full
    sql.RawBytes
    support.
  • Intelligent
    LONG DATA
    handling in prepared statements
  • Secure
    LOAD DATA LOCAL INFILE
    support with file allowlisting and
    io.Reader
    support
  • Optional
    time.Time
    parsing
  • Optional placeholder interpolation

Requirements

  • Go 1.10 or higher. We aim to support the 3 latest versions of Go.
  • MySQL (4.1+), MariaDB, Percona Server, Google CloudSQL or Sphinx (2.2.3+)

Installation

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

bash
$ go get -u github.com/go-sql-driver/mysql
Make sure Git is installed on your machine and in your system's
PATH
.

Usage

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
API then.

Use

mysql
as
driverName
and a valid DSN as
dataSourceName
:
import "database/sql"
import _ "github.com/go-sql-driver/mysql"

db, err := sql.Open("mysql", "user:[email protected]/dbname") if err != nil { panic(err) } // See "Important settings" section. db.SetConnMaxLifetime(time.Minute * 3) db.SetMaxOpenConns(10) db.SetMaxIdleConns(10)

Examples are available in our Wiki.

Important settings

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 to (or greater than)
db.SetMaxOpenConns()
. When it is smaller than
SetMaxOpenConns()
, connections can be opened and closed very frequently than you expect. Idle connections can be closed by the
db.SetConnMaxLifetime()
. If you want to close idle connections more rapidly, you can use
db.SetConnMaxIdleTime()
since Go 1.15.

DSN (Data Source Name)

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:[email protected](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, leave

dbname
empty:
/
This has the same effect as an empty DSN string: ```
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.

Password

Passwords can consist of any character. Escaping is not necessary.

Protocol

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

Address

For TCP and UDP networks, addresses have the form host[:port]. If port is omitted, the default port will be used. If host is a literal IPv6 address, it must be enclosed in square brackets. The functions net.JoinHostPort and net.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

Parameters are case-sensitive!

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.

allowAllFiles

Type: bool Valid Values: true, false Default: false ```

allowAllFiles=true
disables the file allowlist for
LOAD DATA LOCAL INFILE
and allows all files. Might be insecure!
allowCleartextPasswords
Type:           bool
Valid Values:   true, false
Default:        false

allowCleartextPasswords=true
allows using the cleartext client side plugin if required by an account, such as one defined with the PAM 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 include TLS / SSL, IPsec, or a private network.
allowNativePasswords
Type:           bool
Valid Values:   true, false
Default:        true

allowNativePasswords=false
disallows the usage of MySQL native password method.
allowOldPasswords
Type:           bool
Valid Values:   true, false
Default:        false

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.
charset
Type:           string
Valid Values:   
Default:        none

Sets the charset used for client-server interaction (

"SET NAMES "
). 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) with fallback to
utf8
for older servers (
charset=utf8mb4,utf8
).

Usage of the

charset
parameter is discouraged because it issues additional queries to the server. Unless you need the fallback behavior, please use
collation
instead.
checkConnLiveness
Type:           bool
Valid Values:   true, false
Default:        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.
collation
Type:           string
Valid Values:   
Default:        utf8mb4_general_ci

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.

A list of valid charsets for a server is retrievable with

SHOW 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).

clientFoundRows
Type:           bool
Valid Values:   true, false
Default:        false

clientFoundRows=true
causes an UPDATE to return the number of matching rows instead of the number of rows changed.
columnsWithAlias
Type:           bool
Valid Values:   true, false
Default:        false

When

columnsWithAlias
is true, calls to
sql.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 return

u.id
instead of just
id
if
columnsWithAlias=true
.
interpolateParams
Type:           bool
Valid Values:   true, false
Default:        false

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
.

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

loc
Type:           string
Valid Values:   
Default:        UTC

Sets the location for time.Time values (when using

parseTime=true
). "Local" sets the system's location. See time.LoadLocation for details.

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

Please keep in mind, that param values must be url.QueryEscape'ed. Alternatively you can manually replace the

/
with
%2F
. For example
US/Pacific
would be
loc=US%2FPacific
.
maxAllowedPacket
Type:          decimal number
Default:       4194304

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.
multiStatements
Type:           bool
Valid Values:   true, false
Default:        false

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.

When

multiStatements
is used,
?
parameters must only be used in the first statement.
parseTime
Type:           bool
Valid Values:   true, false
Default:        false

parseTime=true
changes the output type of
DATE
and
DATETIME
values to
time.Time
instead of
[]byte
/
string
The date or datetime like
0000-00-00 00:00:00
is converted into zero value of
time.Time
.
readTimeout
Type:           duration
Default:        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".

rejectReadOnly
Type:           bool
Valid Values:   true, false
Default:        false

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

Note that this should be a fairly rare case, as an automatic failover normally happens when the primary is down, and the race condition shouldn't happen unless it comes back up online as soon as the failover is kicked off. On the other hand, when this happens, a MySQL application can get stuck on a read-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't supposed to happen, setting this on some MySQL providers (such as AWS Aurora) is safer for failovers.

Note that ERROR 1290 can be returned for a

read-only
server and this option will cause a retry for that error. However the same error number is used for some other cases. You should ensure your application will never cause an ERROR 1290 except for
read-only
mode when enabling this option.
serverPubKey
Type:           string
Valid Values:   
Default:        none

Server public keys can be registered with

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

timeout
Type:           duration
Default:        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".

tls
Type:           bool / string
Valid Values:   true, false, skip-verify, preferred, 
Default:        false

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
.
writeTimeout
Type:           duration
Default:        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".

System Variables

Any other parameters are interpreted as system variables: *

=
:
SET =
*
=
:
SET =
*
=%27%27
:
SET =''

Rules: * The values for string variables must be quoted with

'
. * The values must also be url.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'

Examples

[email protected](/path/to/socket)/dbname
root:[email protected](/tmp/mysql.sock)/myDatabase?loc=Local
user:[email protected](localhost:5555)/dbname?tls=skip-verify&autocommit=true

Treat warnings as errors by setting the system variable

sql_mode
:

user:[email protected]/dbname?sql_mode=TRADITIONAL

TCP via IPv6:

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

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

id:[email protected](your-amazonaws-uri.com:3306)/dbname

Google Cloud SQL on App Engine:

user:[email protected](/cloudsql/project-id:region-name:instance-name)/dbname

TCP using default port (3306) on localhost:

user:[email protected]/dbname?charset=utf8mb4,utf8&sys_var=esc%40ped

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

user:[email protected]/dbname

No Database preselected:

user:[email protected]/

Connection pool and timeouts

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. The read, write, and dial timeouts for each individual connection are configured with the DSN parameters
readTimeout
,
writeTimeout
, and
timeout
, respectively.

ColumnType
Support

This driver supports the

ColumnType
interface introduced in Go 1.8, with the exception of
ColumnType.Length()
, which is currently not supported.

context.Context
Support

Go 1.8 added

database/sql
support for
context.Context
. This driver supports query timeouts and cancellation via contexts. See context support in the database/sql package for more details.

LOAD DATA LOCAL INFILE
support

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

_
):
go
import "github.com/go-sql-driver/mysql"

Files must be explicitly allowed by registering them with

mysql.RegisterLocalFile(filepath)
(recommended) or the allowlist check must be deactivated by using the DSN parameter
allowAllFiles=true
(Might be insecure!).

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::
then. Choose different names for different handlers and
DeregisterReaderHandler
when you don't need it anymore.

See the godoc of Go-MySQL-Driver for details.

time.Time
support

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.

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
with the
loc
DSN parameter.

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
.

Unicode support

Since version 1.5 Go-MySQL-Driver automatically uses the collation

utf8mb4_general_ci
by default.

Other collations / charsets can be set using the

collation
DSN parameter.

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
parameter should be preferred to set another collation / charset than the default.

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

Testing / Development

To run the driver tests you may need to adjust the configuration. See the Testing 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 an open issue or review a pull request.

See the Contribution Guidelines for details.


License

Go-MySQL-Driver is licensed under the Mozilla 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 can use the unchanged source code both in private and commercially. * 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). * You needn't publish the source code of your library as long as the files licensed under the MPL 2.0 are unchanged.

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

You can read the full terms here: LICENSE.

Go Gopher and MySQL Dolphin

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.