Go-MySQL-Driver

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

Current tagged Release: March 2, 2013 (stable beta 4)

(master branch)

---

• Features
• Requirements
• Installation
• Usage
  • DSN (Data Source Name)
    • Password
    • Protocol
    • Address
    • Parameters
    • Examples
  • LOAD DATA LOCAL INFILE 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 Sockets
• Automatic handling of broken connections
• Automatic Connection-Pooling (by database/sql package)
• Supports queries larger than 16MB
• Intelligent LONG DATA handling in prepared statements
• Secure LOAD DATA LOCAL INFILE support with file Whitelisting and io.Reader support

Requirements

• Go 1.0.3 or higher
• MySQL (Version 4.1 or higher), MariaDB or Percona Server

---

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, so all you need to do is to import the driver and open a new database connection with the given driver.

Use mysql as driverName and a valid DSN as dataSourceName

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

db, e := sql.Open("mysql", "user:password@/dbname?charset=utf8")

All further methods are listed here: http://golang.org/pkg/database/sql

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 of the databasename, all values are optional. So the minimal DSN is:

/dbname

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

/

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

Possible Parameters are:

• timeout: 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.
• charset: "SET NAMES value". If multiple charsets are set (seperated by a comma), the following charset is used if setting the charset failes. This enables support for utf8mb4 (introduced in MySQL 5.5.3) with fallback to utf8 for older servers.
• allowAllFiles: allowAllFiles=true disables the file Whitelist for LOAD DATA LOCAL INFILE and allows all files. Might be insecure!
• (pending) tls: will enable SSL/TLS-Encryption
• (pending) compress: will enable Compression

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"

Examples

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

user:password@tcp(localhost:5555)/dbname?charset=utf8&autocommit=true

user:password@tcp([de:ad:be:ef::ca:fe]:80)/dbname?charset=utf8mb4,utf8

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) (reccommended) 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 also the godoc of Go-MySQL-Driver

Testing / Development

To run the driver tests you may need to adjust the configuration. See this 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.

---

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 as also commercial
• You needn't publish the source code of your library as long the files licensed under the MPL 2.0 are unchanged
• 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)

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

You can read the full terms here: LICENSE