mysql

README

Go-MySQL-Driver

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

Latest stable Release: Version 1.2 (June 03, 2014)

---

• Features
• Requirements
• Installation
• Usage
  • DSN (Data Source Name)
    • Password
    • Protocol
    • Address
    • Parameters
    • Examples
  • LOAD DATA LOCAL INFILE support
  • time.Time support
  • Unicode support
• Testing / Development
• License

---

Features

• Lightweight and fast
• Native Go implementation. No C-bindings, just pure Go
• Connections over TCP/IPv4, TCP/IPv6 or Unix domain sockets
• 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 Whitelisting and io.Reader support
• Optional time.Time parsing
• Optional placeholder interpolation

Requirements

• Go 1.2 or higher
• 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:

$ go get 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:password@/dbname")

Examples are available in our Wiki.

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: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, leave dbname empty:

/

This has the same effect as an empty DSN string:

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

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

collation

Type:           string
Valid Values:   <name>
Default:        utf8_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.

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 blacklisted as they may introduce a SQL injection vulnerability!

loc

Type:           string
Valid Values:   <escaped name>
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.

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

strict

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

strict=true enables the strict mode in which MySQL warnings are treated as errors.

By default MySQL also treats notes as warnings. Use sql_notes=false to ignore notes. See the examples for an DSN example.

timeout

Type:           decimal number
Default:        OS default

Driver side connection timeout. The value must be a string of decimal numbers, each with optional fraction and a unit suffix ( "ms", "s", "m", "h" ), such as "30s", "0.5m" or "1m30s". To set a server side timeout, use the parameter wait_timeout.

tls

Type:           bool / string
Valid Values:   true, false, skip-verify, <name>
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). Use a custom value registered with mysql.RegisterTLSConfig.

System Variables

All other parameters are interpreted as system variables:

• autocommit: "SET autocommit=<value>"
• time_zone: "SET time_zone=<value>"
• tx_isolation: "SET tx_isolation=<value>"
• param: "SET <param>=<value>"

The values must be url.QueryEscape'ed!

Examples

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

Use the strict mode but ignore notes:

user:password@/dbname?strict=true&sql_notes=false

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@cloudsql(project-id: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@/

LOAD DATA LOCAL INFILE support

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

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.

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

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

Alternatively you can use the NullTime type as the scan destination, which works with both time.Time and string / []byte.

Unicode support

Since version 1.1 Go-MySQL-Driver automatically uses the collation utf8_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/5.7/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

Documentation

Overview

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

The driver should be used via the database/sql package:

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

db, err := sql.Open("mysql", "user:password@/dbname")

See https://github.com/go-sql-driver/mysql#usage for details

Index

• Variables
• func DeregisterLocalFile(filePath string)
• func DeregisterReaderHandler(name string)
• func DeregisterTLSConfig(key string)
• func RegisterDial(net string, dial DialFunc)
• func RegisterLocalFile(filePath string)
• func RegisterReaderHandler(name string, handler func() io.Reader)
• func RegisterTLSConfig(key string, config *tls.Config) error
• func SetLogger(logger Logger) error
• type DialFunc
• type Logger
• type MySQLDriver
  • func (d MySQLDriver) Open(dsn string) (driver.Conn, error)
• type MySQLError
  • func (me *MySQLError) Error() string
• type MySQLWarning
• type MySQLWarnings
  • func (mws MySQLWarnings) Error() string
• type NullTime
  • func (nt *NullTime) Scan(value interface{}) (err error)
  • func (nt NullTime) Value() (driver.Value, error)

Variables

var (
	ErrInvalidConn       = errors.New("Invalid Connection")
	ErrMalformPkt        = errors.New("Malformed Packet")
	ErrNoTLS             = errors.New("TLS encryption requested but server does not support TLS")
	ErrOldPassword       = errors.New("This user requires old password authentication. If you still want to use it, please add 'allowOldPasswords=1' to your DSN. See also https://github.com/go-sql-driver/mysql/wiki/old_passwords")
	ErrCleartextPassword = errors.New("This user requires clear text authentication. If you still want to use it, please add 'allowCleartextPasswords=1' to your DSN.")
	ErrUnknownPlugin     = errors.New("The authentication plugin is not supported.")
	ErrOldProtocol       = errors.New("MySQL-Server does not support required Protocol 41+")
	ErrPktSync           = errors.New("Commands out of sync. You can't run this command now")
	ErrPktSyncMul        = errors.New("Commands out of sync. Did you run multiple statements at once?")
	ErrPktTooLarge       = errors.New("Packet for query is too large. You can change this value on the server by adjusting the 'max_allowed_packet' variable.")
	ErrBusyBuffer        = errors.New("Busy buffer")
)

Various errors the driver might return. Can change between driver versions.

Functions

func DeregisterLocalFile

func DeregisterLocalFile(filePath string)

DeregisterLocalFile removes the given filepath from the whitelist.

func DeregisterReaderHandler

func DeregisterReaderHandler(name string)

DeregisterReaderHandler removes the ReaderHandler function with the given name from the registry.

func DeregisterTLSConfig

func DeregisterTLSConfig(key string)

DeregisterTLSConfig removes the tls.Config associated with key.

func RegisterDial

func RegisterDial(net string, dial DialFunc)

RegisterDial registers a custom dial function. It can then be used by the network address mynet(addr), where mynet is the registered new network. addr is passed as a parameter to the dial function.

func RegisterLocalFile

func RegisterLocalFile(filePath string)

RegisterLocalFile adds the given file to the file whitelist, so that it can be used by "LOAD DATA LOCAL INFILE <filepath>". Alternatively you can allow the use of all local files with the DSN parameter 'allowAllFiles=true'

filePath := "/home/gopher/data.csv"
mysql.RegisterLocalFile(filePath)
err := db.Exec("LOAD DATA LOCAL INFILE '" + filePath + "' INTO TABLE foo")
if err != nil {
...

func RegisterReaderHandler

func RegisterReaderHandler(name string, handler func() io.Reader)

RegisterReaderHandler registers a handler function which is used to receive a io.Reader. The Reader can be used by "LOAD DATA LOCAL INFILE Reader::<name>". If the handler returns a io.ReadCloser Close() is called when the request is finished.

mysql.RegisterReaderHandler("data", func() io.Reader {
	var csvReader io.Reader // Some Reader that returns CSV data
	... // Open Reader here
	return csvReader
})
err := db.Exec("LOAD DATA LOCAL INFILE 'Reader::data' INTO TABLE foo")
if err != nil {
...

func RegisterTLSConfig

func RegisterTLSConfig(key string, config *tls.Config) error

RegisterTLSConfig registers a custom tls.Config to be used with sql.Open. Use the key as a value in the DSN where tls=value.

rootCertPool := x509.NewCertPool()
pem, err := ioutil.ReadFile("/path/ca-cert.pem")
if err != nil {
    log.Fatal(err)
}
if ok := rootCertPool.AppendCertsFromPEM(pem); !ok {
    log.Fatal("Failed to append PEM.")
}
clientCert := make([]tls.Certificate, 0, 1)
certs, err := tls.LoadX509KeyPair("/path/client-cert.pem", "/path/client-key.pem")
if err != nil {
    log.Fatal(err)
}
clientCert = append(clientCert, certs)
mysql.RegisterTLSConfig("custom", &tls.Config{
    RootCAs: rootCertPool,
    Certificates: clientCert,
})
db, err := sql.Open("mysql", "user@tcp(localhost:3306)/test?tls=custom")

func SetLogger

func SetLogger(logger Logger) error

SetLogger is used to set the logger for critical errors. The initial logger is os.Stderr.

Types

type DialFunc

type DialFunc func(addr string) (net.Conn, error)

DialFunc is a function which can be used to establish the network connection. Custom dial functions must be registered with RegisterDial

type Logger

type Logger interface {
	Print(v ...interface{})
}

Logger is used to log critical error messages.

type MySQLDriver

type MySQLDriver struct{}

This struct is exported to make the driver directly accessible. In general the driver is used via the database/sql package.

func (MySQLDriver) Open

func (d MySQLDriver) Open(dsn string) (driver.Conn, error)

Open new Connection. See https://github.com/go-sql-driver/mysql#dsn-data-source-name for how the DSN string is formated

type MySQLError

type MySQLError struct {
	Number  uint16
	Message string
}

MySQLError is an error type which represents a single MySQL error

func (*MySQLError) Error

func (me *MySQLError) Error() string

type MySQLWarning

type MySQLWarning struct {
	Level   string
	Code    string
	Message string
}

MySQLWarning is an error type which represents a single MySQL warning. Warnings are returned in groups only. See MySQLWarnings

type MySQLWarnings

type MySQLWarnings []MySQLWarning

MySQLWarnings is an error type which represents a group of one or more MySQL warnings

func (MySQLWarnings) Error

func (mws MySQLWarnings) Error() string

type NullTime

type NullTime struct {
	Time  time.Time
	Valid bool // Valid is true if Time is not NULL
}

NullTime represents a time.Time that may be NULL. NullTime implements the Scanner interface so it can be used as a scan destination:

var nt NullTime
err := db.QueryRow("SELECT time FROM foo WHERE id=?", id).Scan(&nt)
...
if nt.Valid {
   // use nt.Time
} else {
   // NULL value
}

This NullTime implementation is not driver-specific

func (*NullTime) Scan

func (nt *NullTime) Scan(value interface{}) (err error)

Scan implements the Scanner interface. The value type must be time.Time or string / []byte (formatted time-string), otherwise Scan fails.

func (NullTime) Value

func (nt NullTime) Value() (driver.Value, error)

Value implements the driver Valuer interface.