mysql
packagemoduleThis package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Tagged version
Modules with tagged versions give importers more predictable builds.
Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
README¶
Go-MySQL-Driver
A MySQL-Driver for Go'sdatabase/sql package
Features
- Lightweight andfast
- Native Go implementation. No C-bindings, just pure Go
- Connections over TCP/IPv4, TCP/IPv6, Unix domain sockets orcustom protocols
- 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 allowlisting andio.Reader
support - Optional
time.Time
parsing - Optional placeholder interpolation
- Supports zlib compression.
Requirements
- Go 1.21 or higher. We aim to support the 3 latest versions of Go.
- MySQL (5.7+) and MariaDB (10.5+) are supported.
- TiDB is supported by PingCAP.
- go-mysql would work with Percona Server, Google CloudSQL or Sphinx (2.2.3+).
- Maintainers won't support them. Do not expect issues are investigated and resolved by maintainers.
- Investigate issues yourself and please send a pull request to fix it.
Installation
Simple install the package to your$GOPATH with thego tool from shell:
go get -u github.com/go-sql-driver/mysql
Make sureGit is installed on your machine and in your system'sPATH
.
Usage
Go MySQL Driver is an implementation of Go'sdatabase/sql/driver
interface. You only need to import the driver and can use the fulldatabase/sql
API then.
Usemysql
asdriverName
and a validDSN asdataSourceName
:
import ("database/sql""time"_ "github.com/go-sql-driver/mysql")// ...db, err := sql.Open("mysql", "user:password@/dbname")if err != nil {panic(err)}// See "Important settings" section.db.SetConnMaxLifetime(time.Minute * 3)db.SetMaxOpenConns(10)db.SetMaxIdleConns(10)
Examples are available in our Wiki.
Important settings
db.SetConnMaxLifetime()
is required to ensure connections are closed by the driver safely before connection is closed by MySQL server, OS, or other middlewares. Since some middlewares close idle connections by 5 minutes, we recommend timeout shorter than 5 minutes. This setting helps load balancing and changing system variables too.
db.SetMaxOpenConns()
is highly recommended to limit the number of connection used by the application. There is no recommended limit number because it depends on application and MySQL server.
db.SetMaxIdleConns()
is recommended to be set same todb.SetMaxOpenConns()
. When it is smaller thanSetMaxOpenConns()
, connections can be opened and closed much more frequently than you expect. Idle connections can be closed by thedb.SetConnMaxLifetime()
. If you want to close idle connections more rapidly, you can usedb.SetConnMaxIdleTime()
since Go 1.15.
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, leavedbname
empty:
/
This has the same effect as an empty DSN string:
dbname
is escaped byPathEscape() since v1.8.0. If your database name isdbname/withslash
, it becomes:
/dbname%2Fwithslash
Alternatively,Config.FormatDSN can be used to create a DSN string by filling a struct.
Password
Passwords can consist of any character. Escaping isnot necessary.
Protocol
Seenet.Dial for more information which networks are available.In general you should use a Unix domain socket if available and TCP otherwise for best performance.
Address
For TCP and UDP networks, addresses have the formhost[:port]
.Ifport
is omitted, the default port will be used.Ifhost
is a literal IPv6 address, it must be enclosed in square brackets.The functionsnet.JoinHostPort andnet.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!
Notice that any oftrue
,TRUE
,True
or1
is accepted to stand for a true boolean value. Not surprisingly, false can be specified as any of:false
,FALSE
,False
or0
.
allowAllFiles
Type: boolValid Values: true, falseDefault: false
allowAllFiles=true
disables the file allowlist forLOAD DATA LOCAL INFILE
and allowsall files.Might be insecure!
allowCleartextPasswords
Type: boolValid Values: true, falseDefault: false
allowCleartextPasswords=true
allows using thecleartext client side plugin if required by an account, such as one defined with thePAM authentication plugin. Sending passwords in clear text may be a security problem in some configurations. To avoid problems if there is any possibility that the password would be intercepted, clients should connect to MySQL Server using a method that protects the password. Possibilities includeTLS / SSL, IPsec, or a private network.
allowFallbackToPlaintext
Type: boolValid Values: true, falseDefault: false
allowFallbackToPlaintext=true
acts like a--ssl-mode=PREFERRED
MySQL client as described inCommand Options for Connecting to the Server
allowNativePasswords
Type: boolValid Values: true, falseDefault: true
allowNativePasswords=false
disallows the usage of MySQL native password method.
allowOldPasswords
Type: boolValid Values: true, falseDefault: false
allowOldPasswords=true
allows the usage of the insecure old password method. This should be avoided, but is necessary in some cases. See alsothe old_passwords wiki page.
charset
Type: stringValid 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 fails. This enables for example support forutf8mb4
(introduced in MySQL 5.5.3) with fallback toutf8
for older servers (charset=utf8mb4,utf8
).
See alsoUnicode Support.
checkConnLiveness
Type: boolValid Values: true, falseDefault: true
On supported platforms connections retrieved from the connection pool are checked for liveness before using them. If the check fails, the respective connection is marked as bad and the query retried with another connection.checkConnLiveness=false
disables this liveness check of connections.
collation
Type: stringValid Values: <name>Default: utf8mb4_general_ci
Sets the collation used for client-server interaction on connection. In contrast tocharset
,collation
does not issue additional queries. If the specified collation is unavailable on the target server, the connection will fail.
A list of valid charsets for a server is retrievable withSHOW COLLATION
.
The default collation (utf8mb4_general_ci
) is supported from MySQL 5.5. You should use an older collation (e.g.utf8_general_ci
) for older MySQL.
Collations for charset "ucs2", "utf16", "utf16le", and "utf32" can not be used (ref).
See alsoUnicode Support.
clientFoundRows
Type: boolValid Values: true, falseDefault: false
clientFoundRows=true
causes an UPDATE to return the number of matching rows instead of the number of rows changed.
columnsWithAlias
Type: boolValid Values: true, falseDefault: false
WhencolumnsWithAlias
is true, calls tosql.Rows.Columns()
will return the table alias and the column name separated by a dot. For example:
SELECT u.id FROM users as u
will returnu.id
instead of justid
ifcolumnsWithAlias=true
.
compress
Type: boolValid Values: true, falseDefault: false
Toggles zlib compression. false by default.
interpolateParams
Type: boolValid Values: true, falseDefault: false
IfinterpolateParams
is true, placeholders (?
) in calls todb.Query()
anddb.Exec()
are interpolated into a single query string with given parameters. This reduces the number of roundtrips, since the driver has to prepare a statement, execute it with given parameters and close the statement again withinterpolateParams=false
.
This can not be used together with the multibyte encodings BIG5, CP932, GB2312, GBK or SJIS. These are rejected as they mayintroduce a SQL injection vulnerability!
loc
Type: stringValid Values: <escaped name>Default: UTC
Sets the location for time.Time values (when usingparseTime=true
)."Local" sets the system's location. Seetime.LoadLocation for details.
Note that this sets the location for time.Time values but does not change MySQL'stime_zone setting. For that see thetime_zone system variable, which can also be set as a DSN parameter.
Please keep in mind, that param values must beurl.QueryEscape'ed. Alternatively you can manually replace the/
with%2F
. For exampleUS/Pacific
would beloc=US%2FPacific
.
timeTruncate
Type: durationDefault: 0
Truncate time values to the specified duration. The value must be a decimal number with a unit suffix ("ms","s","m","h"), such as"30s","0.5m" or"1m30s".
maxAllowedPacket
Type: decimal numberDefault: 64*1024*1024
Max packet size allowed in bytes. The default value is 64 MiB and should be adjusted to match the server settings.maxAllowedPacket=0
can be used to automatically fetch themax_allowed_packet
variable from serveron every connection.
multiStatements
Type: boolValid Values: true, falseDefault: false
Allow multiple statements in one query. This can be used to bach multiple queries. UseRows.NextResultSet() to get result of the second and subsequent queries.
WhenmultiStatements
is used,?
parameters must only be used in the first statement.interpolateParams can be used to avoid this limitation unless prepared statement is used explicitly.
It's possible to access the last inserted ID and number of affected rows for multiple statements by usingsql.Conn.Raw()
and themysql.Result
. For example:
conn, _ := db.Conn(ctx)conn.Raw(func(conn any) error { ex := conn.(driver.Execer) res, err := ex.Exec(` UPDATE point SET x = 1 WHERE y = 2; UPDATE point SET x = 2 WHERE y = 3; `, nil) // Both slices have 2 elements. log.Print(res.(mysql.Result).AllRowsAffected()) log.Print(res.(mysql.Result).AllLastInsertIds())})
parseTime
Type: boolValid Values: true, falseDefault: false
parseTime=true
changes the output type ofDATE
andDATETIME
values totime.Time
instead of[]byte
/string
The date or datetime like0000-00-00 00:00:00
is converted into zero value oftime.Time
.
readTimeout
Type: durationDefault: 0
I/O read timeout. The value must be a decimal number with a unit suffix ("ms","s","m","h"), such as"30s","0.5m" or"1m30s".
rejectReadOnly
Type: boolValid Values: true, falseDefault: false
rejectReadOnly=true
causes the driver to reject read-only connections. Thisis for a possible race condition during an automatic failover, where the mysqlclient gets connected to a read-only replica after the failover.
Note that this should be a fairly rare case, as an automatic failover normallyhappens when the primary is down, and the race condition shouldn't happenunless it comes back up online as soon as the failover is kicked off. On theother hand, when this happens, a MySQL application can get stuck on aread-only connection until restarted. It is however fairly easy to reproduce,for example, using a manual failover on AWS Aurora's MySQL-compatible cluster.
If you are not relying on read-only transactions to reject writes that aren'tsupposed to happen, setting this on some MySQL providers (such as AWS Aurora)is safer for failovers.
Note that ERROR 1290 can be returned for aread-only
server and this option willcause a retry for that error. However the same error number is used for someother cases. You should ensure your application will never cause an ERROR 1290except forread-only
mode when enabling this option.
serverPubKey
Type: stringValid Values: <name>Default: none
Server public keys can be registered withmysql.RegisterServerPubKey
, which can then be used by the assigned name in the DSN.Public keys are used to transmit encrypted data, e.g. for authentication.If the server's public key is known, it should be set manually to avoid expensive and potentially insecure transmissions of the public key from the server to the client each time it is required.
timeout
Type: durationDefault: OS default
Timeout for establishing connections, aka dial timeout. The value must be a decimal number with a unit suffix ("ms","s","m","h"), such as"30s","0.5m" or"1m30s".
tls
Type: bool / stringValid Values: true, false, skip-verify, preferred, <name>Default: false
tls=true
enables TLS / SSL encrypted connection to the server. Useskip-verify
if you want to use a self-signed or invalid certificate (server side) or usepreferred
to use TLS only when advertised by the server. This is similar toskip-verify
, but additionally allows a fallback to a connection which is not encrypted. Neitherskip-verify
norpreferred
add any reliable security. You can use a custom TLS config after registering it withmysql.RegisterTLSConfig
.
writeTimeout
Type: durationDefault: 0
I/O write timeout. The value must be a decimal number with a unit suffix ("ms","s","m","h"), such as"30s","0.5m" or"1m30s".
connectionAttributes
Type: comma-delimited string of user-defined "key:value" pairsValid Values: (<name1>:<value1>,<name2>:<value2>,...)Default: none
Connection attributes are key-value pairs that application programs can pass to the server at connect time.
Any other parameters are interpreted as system variables:
<boolean_var>=<value>
:SET <boolean_var>=<value>
<enum_var>=<value>
:SET <enum_var>=<value>
<string_var>=%27<value>%27
:SET <string_var>='<value>'
Rules:
- The values for string variables must be quoted with
'
. - The values must also beurl.QueryEscape'ed!(which implies values of string variables must be wrapped with
%27
).
Examples:
autocommit=1
:SET autocommit=1
time_zone=%27Europe%2FParis%27
:SET time_zone='Europe/Paris'
transaction_isolation=%27REPEATABLE-READ%27
:SET transaction_isolation='REPEATABLE-READ'
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
Treat warnings as errors by setting the system variablesql_mode
:
user:password@/dbname?sql_mode=TRADITIONAL
TCP via IPv6:
user:password@tcp([de:ad:be:ef::ca:fe]:80)/dbname?timeout=90s&collation=utf8mb4_unicode_ci
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:password@unix(/cloudsql/project-id:region-name: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@/
Connection pool and timeouts
The connection pool is managed by Go's database/sql package. For details on how to configure the size of the pool and how long connections stay in the pool see*DB.SetMaxOpenConns
,*DB.SetMaxIdleConns
, and*DB.SetConnMaxLifetime
in thedatabase/sql documentation. The read, write, and dial timeouts for each individual connection are configured with the DSN parametersreadTimeout
,writeTimeout
, andtimeout
, respectively.
ColumnType
Support
This driver supports theColumnType
interface introduced in Go 1.8, with the exception ofColumnType.Length()
, which is currently not supported. All Unsigned database type names will be returnedUNSIGNED
withINT
,TINYINT
,SMALLINT
,MEDIUMINT
,BIGINT
.
context.Context
Support
Go 1.8 addeddatabase/sql
support forcontext.Context
. This driver supports query timeouts and cancellation via contexts.Seecontext support in the database/sql package for more details.
[!IMPORTANT]The
QueryContext
,ExecContext
, etc. variants provided bydatabase/sql
will cause the connection to be closed if the provided context is cancelled or timed out before the result is received by the driver.
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 explicitly allowed by registering them withmysql.RegisterLocalFile(filepath)
(recommended) or the allowlist check must be deactivated by using the DSN parameterallowAllFiles=true
(Might be insecure!).
To use aio.Reader
a handler function must be registered withmysql.RegisterReaderHandler(name, handler)
which returns aio.Reader
orio.ReadCloser
. The Reader is available with the filepathReader::<name>
then. Choose different names for different handlers andDeregisterReaderHandler
when you don't need it anymore.
See thegodoc of Go-MySQL-Driver for details.
time.Time
support
The default internal output type of MySQLDATE
andDATETIME
values is[]byte
which allows you to scan the value into a[]byte
,string
orsql.RawBytes
variable in your program.
However, many want to scan MySQLDATE
andDATETIME
values intotime.Time
variables, which is the logical equivalent in Go toDATE
andDATETIME
in MySQL. You can do that by changing the internal output type from[]byte
totime.Time
with the DSN parameterparseTime=true
. You can set the defaulttime.Time
location with theloc
DSN parameter.
Caution: As of Go 1.1, this makestime.Time
the only variable type you can scanDATE
andDATETIME
values into. This breaks for examplesql.RawBytes
support.
Unicode support
Since version 1.5 Go-MySQL-Driver automatically uses the collation utf8mb4_general_ci
by default.
Other charsets / collations can be set using thecharset
orcollation
DSN parameter.
- When only the
charset
is specified, theSET NAMES <charset>
query is sent and the server's default collation is used. - When both the
charset
andcollation
are specified, theSET NAMES <charset> COLLATE <collation>
query is sent. - When only the
collation
is specified, the collation is specified in the protocol handshake and theSET NAMES
query is not sent. This can save one roundtrip, but note that the server may ignore the specified collation silently and use the server's default charset/collation instead.
Seehttp://dev.mysql.com/doc/refman/8.0/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 theTesting 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 anopen issue or review apull request.
See theContribution Guidelines for details.
License
Go-MySQL-Driver is licensed under theMozilla 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 canuse theunchanged source code both in private and commercially.
- When distributing, youmust publish the source code of anychanged 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).
- Youneedn't publish the source code of your library as long as the files licensed under the MPL 2.0 areunchanged.
Please read theMPL 2.0 FAQ if you have further questions regarding the license.
You can read the full terms here:LICENSE.
Documentation¶
Overview¶
Package mysql provides a MySQL driver for Go's database/sql package.
The driver should be used via the database/sql package:
import "database/sql"import _ "github.com/go-sql-driver/mysql"db, err := sql.Open("mysql", "user:password@/dbname")
Seehttps://github.com/go-sql-driver/mysql#usage for details
Index¶
- Variables
- func DeregisterDialContext(net string)
- func DeregisterLocalFile(filePath string)
- func DeregisterReaderHandler(name string)
- func DeregisterServerPubKey(name string)
- func DeregisterTLSConfig(key string)
- func NewConnector(cfg *Config) (driver.Connector, error)
- func RegisterDial(network string, dial DialFunc)deprecated
- func RegisterDialContext(net string, dial DialContextFunc)
- func RegisterLocalFile(filePath string)
- func RegisterReaderHandler(name string, handler func() io.Reader)
- func RegisterServerPubKey(name string, pubKey *rsa.PublicKey)
- func RegisterTLSConfig(key string, config *tls.Config) error
- func SetLogger(logger Logger) error
- type Config
- type DialContextFunc
- type DialFuncdeprecated
- type Logger
- type MySQLDriver
- type MySQLError
- type NopLogger
- type NullTimedeprecated
- type Option
- type Result
Constants¶
This section is empty.
Variables¶
var (ErrInvalidConn =errors.New("invalid connection")ErrMalformPkt =errors.New("malformed packet")ErrNoTLS =errors.New("TLS requested but server does not support TLS")ErrCleartextPassword =errors.New("this user requires clear text authentication. If you still want to use it, please add 'allowCleartextPasswords=1' to your DSN")ErrNativePassword =errors.New("this user requires mysql native password authentication")ErrOldPassword =errors.New("this user requires old password authentication. If you still want to use it, please add 'allowOldPasswords=1' to your DSN. See also https://github.com/go-sql-driver/mysql/wiki/old_passwords")ErrUnknownPlugin =errors.New("this authentication plugin is not supported")ErrOldProtocol =errors.New("MySQL server does not support required protocol 41+")ErrPktSync =errors.New("commands out of sync. You can't run this command now")ErrPktSyncMul =errors.New("commands out of sync. Did you run multiple statements at once?")ErrPktTooLarge =errors.New("packet for query is too large. Try adjusting the `Config.MaxAllowedPacket`")ErrBusyBuffer =errors.New("busy buffer"))
Various errors the driver might return. Can change between driver versions.
Functions¶
funcDeregisterDialContext¶added inv1.8.0
func DeregisterDialContext(netstring)
DeregisterDialContext removes the custom dial function registered with the given net.
funcDeregisterLocalFile¶
func DeregisterLocalFile(filePathstring)
DeregisterLocalFile removes the given filepath from the allowlist.
funcDeregisterReaderHandler¶
func DeregisterReaderHandler(namestring)
DeregisterReaderHandler removes the ReaderHandler function withthe given name from the registry.
funcDeregisterServerPubKey¶added inv1.4.0
func DeregisterServerPubKey(namestring)
DeregisterServerPubKey removes the public key registered with the given name.
funcDeregisterTLSConfig¶added inv1.1.0
func DeregisterTLSConfig(keystring)
DeregisterTLSConfig removes the tls.Config associated with key.
funcNewConnector¶added inv1.5.0
NewConnector returns new driver.Connector.
funcRegisterDialdeprecatedadded inv1.2.0
funcRegisterDialContext¶added inv1.5.0
func RegisterDialContext(netstring, dialDialContextFunc)
RegisterDialContext registers a custom dial function. It can then be used by thenetwork address mynet(addr), where mynet is the registered new network.The current context for the connection and its address is passed to the dial function.
funcRegisterLocalFile¶
func RegisterLocalFile(filePathstring)
RegisterLocalFile adds the given file to the file allowlist,so that it can be used by "LOAD DATA LOCAL INFILE <filepath>".Alternatively you can allow the use of all local files withthe DSN parameter 'allowAllFiles=true'
filePath := "/home/gopher/data.csv"mysql.RegisterLocalFile(filePath)err := db.Exec("LOAD DATA LOCAL INFILE '" + filePath + "' INTO TABLE foo")if err != nil {...
funcRegisterReaderHandler¶
RegisterReaderHandler registers a handler function which is usedto receive a io.Reader.The Reader can be used by "LOAD DATA LOCAL INFILE Reader::<name>".If the handler returns a io.ReadCloser Close() is called when therequest is finished.
mysql.RegisterReaderHandler("data", func() io.Reader {var csvReader io.Reader // Some Reader that returns CSV data... // Open Reader herereturn csvReader})err := db.Exec("LOAD DATA LOCAL INFILE 'Reader::data' INTO TABLE foo")if err != nil {...
funcRegisterServerPubKey¶added inv1.4.0
RegisterServerPubKey registers a server RSA public key which can be used tosend data in a secure manner to the server without receiving the public keyin a potentially insecure way from the server first.Registered keys can afterwards be used adding serverPubKey=<name> to the DSN.
Note: The provided rsa.PublicKey instance is exclusively owned by the driverafter registering it and may not be modified.
data, err := os.ReadFile("mykey.pem")if err != nil {log.Fatal(err)}block, _ := pem.Decode(data)if block == nil || block.Type != "PUBLIC KEY" {log.Fatal("failed to decode PEM block containing public key")}pub, err := x509.ParsePKIXPublicKey(block.Bytes)if err != nil {log.Fatal(err)}if rsaPubKey, ok := pub.(*rsa.PublicKey); ok {mysql.RegisterServerPubKey("mykey", rsaPubKey)} else {log.Fatal("not a RSA public key")}
funcRegisterTLSConfig¶added inv1.1.0
RegisterTLSConfig registers a custom tls.Config to be used with sql.Open.Use the key as a value in the DSN where tls=value.
Note: The provided tls.Config is exclusively owned by the driver afterregistering it.
rootCertPool := x509.NewCertPool()pem, err := os.ReadFile("/path/ca-cert.pem")if err != nil { log.Fatal(err)}if ok := rootCertPool.AppendCertsFromPEM(pem); !ok { log.Fatal("Failed to append PEM.")}clientCert := make([]tls.Certificate, 0, 1)certs, err := tls.LoadX509KeyPair("/path/client-cert.pem", "/path/client-key.pem")if err != nil { log.Fatal(err)}clientCert = append(clientCert, certs)mysql.RegisterTLSConfig("custom", &tls.Config{ RootCAs: rootCertPool, Certificates: clientCert,})db, err := sql.Open("mysql", "user@tcp(localhost:3306)/test?tls=custom")
Types¶
typeConfig¶added inv1.3.0
type Config struct {Userstring// UsernamePasswdstring// Password (requires User)Netstring// Network (e.g. "tcp", "tcp6", "unix". default: "tcp")Addrstring// Address (default: "127.0.0.1:3306" for "tcp" and "/tmp/mysql.sock" for "unix")DBNamestring// Database nameParams map[string]string// Connection parametersConnectionAttributesstring// Connection Attributes, comma-delimited string of user-defined "key:value" pairsCollationstring// Connection collation. When set, this will be set in SET NAMES <charset> COLLATE <collation> queryLoc *time.Location// Location for time.Time valuesMaxAllowedPacketint// Max packet size allowedServerPubKeystring// Server public key nameTLSConfigstring// TLS configuration nameTLS *tls.Config// TLS configuration, its priority is higher than TLSConfigTimeouttime.Duration// Dial timeoutReadTimeouttime.Duration// I/O read timeoutWriteTimeouttime.Duration// I/O write timeoutLoggerLogger// Logger// DialFunc specifies the dial function for creating connectionsDialFunc func(ctxcontext.Context, network, addrstring) (net.Conn,error)AllowAllFilesbool// Allow all files to be used with LOAD DATA LOCAL INFILEAllowCleartextPasswordsbool// Allows the cleartext client side pluginAllowFallbackToPlaintextbool// Allows fallback to unencrypted connection if server does not support TLSAllowNativePasswordsbool// Allows the native password authentication methodAllowOldPasswordsbool// Allows the old insecure password methodCheckConnLivenessbool// Check connections for liveness before using themClientFoundRowsbool// Return number of matching rows instead of rows changedColumnsWithAliasbool// Prepend table alias to column namesInterpolateParamsbool// Interpolate placeholders into query stringMultiStatementsbool// Allow multiple statements in one queryParseTimebool// Parse time values to time.TimeRejectReadOnlybool// Reject read-only connections// contains filtered or unexported fields}
Config is a configuration parsed from a DSN string.If a new Config is created instead of being parsed from a DSN string,the NewConfig function should be used, which sets default values.
funcNewConfig¶added inv1.4.0
func NewConfig() *Config
NewConfig creates a new Config and sets default values.
func (*Config)FormatDSN¶added inv1.3.0
FormatDSN formats the given Config into a DSN string which can be passed tothe driver.
Note: useNewConnector anddatabase/sql.OpenDB to open a connection from a*Config.
typeDialContextFunc¶added inv1.5.0
DialContextFunc is a function which can be used to establish the network connection.Custom dial functions must be registered with RegisterDialContext
typeLogger¶added inv1.2.0
type Logger interface {Print(v ...any)}
Logger is used to log critical error messages.
typeMySQLDriver¶added inv1.1.0
type MySQLDriver struct{}
MySQLDriver is exported to make the driver directly accessible.In general the driver is used via the database/sql package.
func (MySQLDriver)Open¶added inv1.1.0
func (dMySQLDriver) Open(dsnstring) (driver.Conn,error)
Open new Connection.Seehttps://github.com/go-sql-driver/mysql#dsn-data-source-name for howthe DSN string is formatted
func (MySQLDriver)OpenConnector¶added inv1.5.0
func (dMySQLDriver) OpenConnector(dsnstring) (driver.Connector,error)
OpenConnector implements driver.DriverContext.
typeMySQLError¶
MySQLError is an error type which represents a single MySQL error
func (*MySQLError)Error¶
func (me *MySQLError) Error()string
func (*MySQLError)Is¶added inv1.7.0
func (me *MySQLError) Is(errerror)bool
typeNopLogger¶added inv1.8.0
type NopLogger struct{}
NopLogger is a nop implementation of the Logger interface.
typeNullTimedeprecated
NullTime represents a time.Time that may be NULL.NullTime implements the Scanner interface soit can be used as a scan destination:
var nt NullTimeerr := db.QueryRow("SELECT time FROM foo WHERE id=?", id).Scan(&nt)...if nt.Valid { // use nt.Time} else { // NULL value}
This NullTime implementation is not driver-specific¶
Deprecated: NullTime doesn't honor the loc DSN parameter.NullTime.Scan interprets a time as UTC, not the loc DSN parameter.Use sql.NullTime instead.
typeOption¶added inv1.8.0
Functional Options Patternhttps://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis
funcBeforeConnect¶added inv1.8.0
BeforeConnect sets the function to be invoked before a connection is established.
funcCharset¶added inv1.9.1
Charset sets the connection charset and collation.
charset is the connection charset.collation is the connection collation. It can be null or empty string.
When collation is not specified, `SET NAMES <charset>` command is sent when the connection is established.When collation is specified, `SET NAMES <charset> COLLATE <collation>` command is sent when the connection is established.
funcEnableCompression¶added inv1.9.0
EnableCompress sets the compression mode.
funcTimeTruncate¶added inv1.8.0
TimeTruncate sets the time duration to truncate time.Time values inquery parameters.
typeResult¶added inv1.8.0
type Result interface {driver.Result// AllRowsAffected returns a slice containing the affected rows for each// executed statement.AllRowsAffected() []int64// AllLastInsertIds returns a slice containing the last inserted ID for each// executed statement.AllLastInsertIds() []int64}
Result exposes data not available through *connection.Result.
This is accessible by executing statements using sql.Conn.Raw() anddowncasting the returned result:
res, err := rawConn.Exec(...)res.(mysql.Result).AllRowsAffected()