A MySQL-Driver for Go's database/sql package
Current tagged Release: January 15, 2013 (beta)
Note: go get
doesn't install the master
branch, but the tag go1
, which build status is always checked before tagging!
- 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](https://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 _ "code.google.com/p/go-mysql-driver/mysql"
db, e := sql.Open("mysql", "user:password@/dbname?charset=utf8")
All further methods are listed here: https://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¶mN=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 NAMESvalue
"- (deprecated)
With Go 1.0.3 this is not necessary anymore. Now closed connections can be automatically detected and handled.keepalive
: Ifvalue
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 everyvalue
seconds without a command. System variables are executed before, so it may be possible to change the wait_timeout value. - (pending)
: will enable SSL/TLS-Encryptiontls
- (pending)
: will enable Compressioncompress
All other parameters are interpreted as system variables:
time_zone
: "SET time_zone='value
'"tx_isolation
: "SET tx_isolation='value
'"param
: "SETparam
=value
"
user@unix(/path/to/socket)/dbname?charset=utf8
user:password@tcp(localhost:5555)/dbname?charset=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