Go-MySQL-Driver

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

Current tagged Release: February 25, 2013 (stable beta 3)

(master branch)

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

Features

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)

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

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:

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

Examples

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@/

Testing / Development

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

realdog/MySQL