Go-MySQL-Driver
A MySQL-Driver for Go's database/sql package
Current tagged Release: Version 1.1 (November 02, 2013)
Features
- Lightweight and fast
- Native Go implementation. No C-bindings, just pure Go
- Connections over TCP/IPv4, TCP/IPv6 or Unix domain sockets
- Automatic handling of broken connections
- Automatic Connection Pooling (by database/sql package)
- Supports queries larger than 16MB
- Full
sql.RawBytes
support. - Intelligent
LONG DATA
handling in prepared statements - Secure
LOAD DATA LOCAL INFILE
support with file Whitelisting andio.Reader
support - Optional
time.Time
parsing
Requirements
- Go 1.1 or higher (use v1.0 for Go 1.0.x)
- 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
.
go get
installs the latest tagged release
Usage
Go MySQL Driver is an implementation of Go's database/sql/driver
interface. You only need to import the driver and can use the full database/sql
API then.
Use mysql
as driverName
and a valid DSN as dataSourceName
:
import "database/sql"
import _ "github.com/go-sql-driver/mysql"
db, err := sql.Open("mysql", "user:password@/dbname")
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&...¶mN=valueN]
A DSN in its fullest form:
username:password@protocol(address)/dbname?param=value
Except for the databasename, all values are optional. So the minimal DSN is:
/dbname
If you do not want to preselect a database, leave dbname
empty:
/
This has the same effect as an empty DSN string:
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 domain 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 domain 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!
allowAllFiles
Type: bool
Valid Values: true, false
Default: false
allowAllFiles=true
disables the file Whitelist for LOAD DATA LOCAL INFILE
and allows all files.
Might be insecure!
allowOldPasswords
Type: bool
Valid Values: true, false
Default: false
allowAllFiles=true
allows the usage of the insecure old password method. This should be avoided, but is necessary in some cases. See also the old_passwords wiki page.
charset
Type: string
Valid Values: <name>
Default: none
Sets the charset used for client-server interaction ("SET NAMES <value>"
). If multiple charsets are set (separated 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 (charset=utf8mb4,utf8
).
clientFoundRows
Type: bool
Valid Values: true, false
Default: false
clientFoundRows=true
causes an UPDATE to return the number of matching rows instead of the number of rows changed.
loc
Type: string
Valid Values: <escaped name>
Default: UTC
Sets the location for time.Time values (when using parseTime=true
). "Local" sets the system's location. See time.LoadLocation for details.
Please keep in mind, that param values must be url.QueryEscape'ed. Alternatively you can manually replace the /
with %2F
. For example US/Pacific
would be loc=US%2FPacific
.
parseTime
Type: bool
Valid Values: true, false
Default: false
parseTime=true
changes the output type of DATE
and DATETIME
values to time.Time
instead of []byte
/ string
strict
Type: bool
Valid Values: true, false
Default: false
strict=true
enables strict mode. MySQL warnings are treated as errors.
timeout
Type: decimal number
Default: OS default
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
.
tls
Type: bool / string
Valid Values: true, false, skip-verify, <name>
Default: false
tls=true
enables TLS / SSL encrypted connection to the server. Use skip-verify
if you want to use a self-signed or invalid certificate (server side). Use a custom value registered with mysql.RegisterTLSConfig
.
System Variables
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>"
The values must be url.QueryEscape'ed!
Examples
user@unix(/path/to/socket)/dbname
root:pw@unix(/tmp/mysql.sock)/myDatabase?loc=Local
user:password@tcp(localhost:5555)/dbname?tls=skip-verify&autocommit=true
TCP via IPv6:
user:password@tcp([de:ad:be:ef::ca:fe]:80)/dbname?timeout=90s
TCP on a remote host, e.g. Amazon RDS:
id:password@tcp(your-amazonaws-uri.com:3306)/dbname
Google Cloud SQL on App Engine:
user@cloudsql(project-id:instance-name)/dbname
TCP using default port (3306) on localhost:
user:password@tcp/dbname&charset=utf8mb4,utf8&sys_var=esc%40ped
Use the default protocol (tcp) and host (localhost:3306):
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)
(recommended) 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 the godoc of Go-MySQL-Driver for details.
time.Time
support
The default internal output type of MySQL DATE
and DATETIME
values is []byte
which allows you to scan the value into a []byte
, string
or sql.RawBytes
variable in your programm.
However, many want to scan MySQL DATE
and DATETIME
values into time.Time
variables, which is the logical opposite in Go to DATE
and DATETIME
in MySQL. You can do that by changing the internal output type from []byte
to time.Time
with the DSN parameter parseTime=true
. You can set the default time.Time
location with the loc
DSN parameter.
Caution: As of Go 1.1, this makes time.Time
the only variable type you can scan DATE
and DATETIME
values into. This breaks for example sql.RawBytes
support.
Alternatively you can use the NullTime
type as the scan destination, which works with both time.Time
and string
/ []byte
.
Unicode support
Since version 1.1 Go-MySQL-Driver automatically uses the collation utf8_general_ci
by default. Adding &charset=utf8
(alias for SET NAMES utf8
) to the DSN is not necessary anymore in most cases.
See http://dev.mysql.com/doc/refman/5.7/en/charset-unicode.html for more details on MySQL's Unicode support.
Testing / Development
To run the driver tests you may need to adjust the configuration. See the Testing 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 or review a pull request.
See the Contribution Guidelines 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