go-sql-driver__mysql

Go-MySQL-Driver

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

---

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