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

Current tagged Release: February 6, 2013 (beta 2 [stable])

(master branch)

Note: go get doesn't install the master branch, but the tag go1, which build status is always checked before tagging!

• Features
• Requirements
• Installation
• Usage
• DSN (Data Source Name)
  • Password
  • Protocol
  • Address
  • Parameters
  • Examples
• Testing / Development
• License

• Lightweight and fast
• Native Go implementation. No C-bindings, just pure Go
• No unsafe operations (e.g. type-conversions)
• Connections over TCP/IPv4, TCP/IPv6 or Unix Sockets
• Automatic handling of broken connections
• Automatic Connection-Pooling (by database/sql package)

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

Simple install the package to your $GOPATH with the [go tool](http://golang.org/cmd/go/ go command) from shell:

$ go get github.com/Go-SQL-Driver/MySQL

Make sure Git is installed on your machine and in your system's PATH.

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.

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:

/

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

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.

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 are case-sensitive!

Possible Parameters are:

• 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.
• (deprecated) keepalive: If value equals 1, the keepalive-time is set to wait_timeout-60, which pings the Server 60 seconds before the MySQL server would close the connection to avoid timeout. If the value is greater than 1, the server gets pinged every value seconds without a command. System variables are executed before, so it may be possible to change the wait_timeout value. With Go 1.0.3 this is not necessary anymore. Now closed connections can be automatically detected and handled.
• (pending) tls: will enable SSL/TLS-Encryption
• (pending) compress: will enable Compression

All other parameters are interpreted as system variables:

• time_zone: "SET time_zone='value'"
• tx_isolation: "SET tx_isolation='value'"
• param: "SET param=value"

user@unix(/path/to/socket)/dbname?charset=utf8

user:password@tcp(localhost:5555)/dbname?charset=utf8mb4,utf8

user:password@tcp([de:ad:be:ef::ca:fe]:80)/dbname

user:password@/dbname

No Database preselected:

user:password@/

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

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