| commit | dfcba35e8da88b7b40a27aadc58ec7d991cc005f | [log] [tgz] |
|---|---|---|
| author | Julien Schmidt <github@julienschmidt.com> | Fri Nov 01 17:30:52 2013 |
| committer | Julien Schmidt <github@julienschmidt.com> | Fri Nov 01 17:30:52 2013 |
| tree | d92ad0346af3483abfa20c6875a0831f74164739 | |
| parent | fdeb5682f67d1859ae53d49ea4a1ac5d033fc747 [diff] | |
| parent | 069f1ba6984b8079e3d95cc61a886eafb71e16f3 [diff] |
Merge pull request #148 from go-sql-driver/v1.0.3 Release v1.0.3
A MySQL-Driver for Go's database/sql package
Current tagged Release: November 01, 2013 (Version 1.0.3)
sql.RawBytes support.LONG DATA handling in prepared statementsLOAD DATA LOCAL INFILE support with file Whitelisting and io.Reader supporttime.Time parsingSimple 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 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, e := sql.Open("mysql", "user:password@/dbname?charset=utf8")
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 domain 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 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 are case-sensitive!
Possible Parameters are:
timeout: 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.charset: 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).allowAllFiles: allowAllFiles=true disables the file Whitelist for LOAD DATA LOCAL INFILE and allows all files. Might be insecure!parseTime: parseTime=true changes the output type of DATE and DATETIME values to time.Time instead of []byte / stringloc: Sets the location for time.Time values (when using parseTime=true). The default is UTC. “Local” sets the system's location. See time.LoadLocation for details.strict: Enable strict mode. MySQL warnings are treated as errors.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”user@unix(/path/to/socket)/dbname
user:password@tcp(localhost:5555)/dbname?charset=utf8&autocommit=true
user:password@tcp([de:ad:be:ef::ca:fe]:80)/dbname?charset=utf8mb4,utf8
user:password@/dbname
No Database preselected:
user:password@/
LOAD DATA LOCAL INFILE supportFor 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 also the godoc of Go-MySQL-Driver
time.Time supportThe 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.
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.
Code changes must be proposed via a Pull Request and must be reviewed. Only LGTM-ed (" Looks good to me ") code may be committed to the master branch.
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:
Please read the MPL 2.0 FAQ if you have further questions regarding the license.
You can read the full terms here: LICENSE