mysql

block/mysql

A tracking fork of go-sql-driver/mysql.

Block depends on a small number of capabilities and defaults that differ from upstream. This fork carries those changes while upstream is merged forward regularly, with the delta kept deliberately small.

The upstream README follows below the separator, edited only where it names the import path or driver name.

What this fork adds

Capability	What it is	Upstream status
QueryResultContext	Executes arbitrary SQL and returns either driver.Rows or driver.Result, matching the server response.	Raised as go-sql-driver/mysql#1793. Merged here as #1.
Warnings()	Exposes the warning count from the last statement, so callers can decide whether to fetch SHOW WARNINGS.	Not yet raised upstream. Merged here as #2.
ConnectionID()	Exposes the server thread ID from the handshake, so a caller can interrupt a running statement with KILL QUERY from another connection without first running SELECT CONNECTION_ID().	Not yet raised upstream.
Auto TLS for RDS hosts	Automatically verifies RDS and Aurora endpoints against the embedded Amazon RDS root bundle. Explicit DSN settings take precedence.	Not yet raised upstream. Merged here as #4.
Driver name changed to block-mysql	Allows this fork and upstream's mysql driver to coexist without duplicate registration.	N/A
Module path changed to github.com/block/mysql	Makes the fork an explicit dependency that survives across module boundaries.	N/A
Always reject read-only connections	Discards connections to a demoted writer after failover. Explicit read-only transactions remain exempt.	Fork policy; merged here as #5.
Test platforms reduced to a smaller set	Tests Linux with MySQL 8.0, 8.4, and 9.7, plus the two previous Go releases against the newest MySQL. Other upstream platforms are untested here.	N/A

The first two are reached through (*sql.Conn).Raw and a structural interface assertion, so a consumer can depend on the capability without a compile-time dependency on this module. See the doc comments in unified.go and warnings.go for the exact contracts.

Auto TLS for RDS hosts

RDS auto-TLS needs no API at all: it applies to any connection whose address looks like an RDS or Aurora endpoint. Anything the DSN specifies still wins, including tls=false, and mysql.RDSTLSConfig() returns the same configuration for an RDS instance reached under a name that doesn't look like one (a CNAME, or a proxy).

It is a property of the address, not of the DSN string. That is what makes it robust inside this driver — a ParseDSN/FormatDSN round trip cannot drop it, unlike a tls=<name> that refers to an entry in a package-global registry. It also means a DSN produced by FormatDSN carries no tls=, so handing that string to something built on upstream go-sql-driver yields a plaintext RDS connection with nothing in the string to suggest otherwise. Open it with block-mysql and the behaviour comes back.

Two partitions are deliberately excluded, because the embedded bundle holds no roots for either: China (*.amazonaws.com.cn, a different suffix) and GovCloud (*.us-gov-*.rds.amazonaws.com, which the suffix check alone would accept). Both keep whatever the DSN asks for; use mysql.RDSTLSConfig() with that partition's own bundle to verify them.

Module path and driver name

The module path is github.com/block/mysql. Upstream's path plus a replace directive would work for a binary, but replace is not inherited across module boundaries: a downstream module importing a library built on this fork gets upstream go-sql-driver instead, with no diagnostic. Depending on how the library reaches the fork's features that is either a compile failure or — worse, and the case that motivated this change — a clean build that fails at runtime. A distinct module path is the only mechanism Go has for expressing a dependency that is not substitutable.

The driver registers as block-mysql, not mysql. This is required rather than cosmetic. Because the module path now differs, a dependency graph that still reaches upstream go-sql-driver anywhere links both packages into one binary, and two sql.Register calls under the same name panic at init. Open connections with:

db, err := sql.Open("block-mysql", dsn)

Read-only connections

Read-only connections are always rejected. Upstream's rejectReadOnly option defaults to off; here the behaviour is unconditional and Config.RejectReadOnly is gone. RDS and Aurora fail over by moving DNS, so a pooled connection to the demoted writer stays open and every write on it fails until the process restarts — with nothing in the DSN or the error to say the connection is the problem. See the rejectReadOnly parameter below for what happens to a DSN that still sets it.

Unless noted above, the DSN format and API follow upstream.

Supported platforms

Narrower than upstream, and deliberately so — CI covers Linux with MySQL LTS (9.7, 8.4, 8.0), plus the two previous Go releases against the newest MySQL.

Upstream additionally tests macOS and Windows runners and four MariaDB versions. Block deploys none of those, so the fork drops them: 21 matrix combinations become 3 (5 test jobs rather than 23, counting the two appended older-Go entries), and no exposure to the Windows-runner TCP dial flake that upstream's own CI also hits. Nothing about the driver is Linux- or MySQL-specific — the platforms are merely untested here, so treat upstream as the authority on them.

Linking both drivers

Where a binary links this fork and upstream, remember that the two packages declare distinct types even though the source is identical. Most importantly, an *mysql.MySQLError produced by this package will not satisfy an errors.As against upstream's *mysql.MySQLError, and vice versa — the check silently returns false rather than failing loudly. Be deliberate about which package each error-inspection site imports, and prefer moving code you control onto one of the two.

The other silent case is sql.Open. Registries in this package are package-level globals, so a RegisterTLSConfig/RegisterLocalFile/ RegisterDialContext call made against the wrong import path errors on use with a message that names the cause — a migration chore, not a trap. A call site that still says sql.Open("mysql", …), however, resolves to whatever upstream's init registered, connects, and behaves correctly until something reaches for QueryResultContext or Warnings() through (*sql.Conn).Raw and the structural assertion fails. Note the asymmetry: with upstream not in the dependency graph the same mistake is benign, failing immediately with sql: unknown driver "mysql". Grep for the literal when both are linked.

Staying current

git remote add upstream https://github.com/go-sql-driver/mysql.git
git fetch upstream
git merge upstream/master

Edits to upstream files are confined to four things: the module path and driver name (go.mod, driver.go, plus doc comments and test call sites that spell either one out), the CI matrix (see Supported platforms), a one-line call in Config.normalize that hands off to rds.go, and the read-only rejection (one condition in packets.go, the parameter in dsn.go, and the read-only-transaction flag in connection.go/transaction.go). The capabilities above live in files upstream does not have, which is what keeps merges near-mechanical.

Additions are cheapest when they follow the same shape: new files, or new methods on existing types, in preference to reworking an upstream code path.

License

MPL-2.0, unchanged from upstream, as are LICENSE and AUTHORS. Modified and added files stay under the MPL and are published here in satisfaction of it. Copyright in the original work remains with The Go-MySQL-Driver Authors.

---

Go-MySQL-Driver

Upstream README follows.

A MySQL-Driver for Go's database/sql package

---

• Features
• Requirements
• Installation
• Usage
  • DSN (Data Source Name)
    • Password
    • Protocol
    • Address
    • Parameters
    • Examples
  • Verifying Server
  • OpenID Connect authentication
  • Connection pool and timeouts
  • context.Context Support
  • ColumnType Support
  • LOAD DATA LOCAL INFILE support
  • time.Time support
  • Unicode support
• Testing / Development
• License

---

Features

• Lightweight and fast
• Native Go implementation. No C-bindings, just pure Go
• Connections over TCP/IPv4, TCP/IPv6, Unix domain sockets or custom 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 and io.Reader support
• Optional time.Time parsing
• Optional placeholder interpolation
• Supports zlib compression and optional zstd compression.

Requirements

• Go 1.25 or higher. We aim to support the 3 latest versions of Go.
• MySQL (8.0+) and MariaDB (10.11+) are supported by maintainers.
• TiDB is supported by PingCAP.
  • Do not ask questions about TiDB in our issue tracker or forum.
  • Document
  • Forum
• 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 the go tool from shell:

go get -u github.com/block/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. You only need to import the driver and can use the full database/sql API then.

Use block-mysql as driverName and a valid DSN as dataSourceName:

import (
	"database/sql"
	"time"

	_ "github.com/block/mysql"
)

// ...

db, err := sql.Open("block-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 to db.SetMaxOpenConns(). When it is smaller than SetMaxOpenConns(), connections can be opened and closed much more frequently than you expect. Idle connections can be closed by the db.SetConnMaxLifetime(). If you want to close idle connections more rapidly, you can use db.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&...&paramN=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:

dbname is escaped by PathEscape() since v1.8.0. If your database name is dbname/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 is not necessary.

Protocol

See net.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 form host[:port]. If port is omitted, the default port will be used. 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!

Notice that any of true, TRUE, True or 1 is accepted to stand for a true boolean value. Not surprisingly, false can be specified as any of: false, FALSE, False or 0.

Type:           bool
Valid Values:   true, false
Default:        false

allowAllFiles=true disables the file allowlist for LOAD DATA LOCAL INFILE and allows all files. Might be insecure!

Type:           bool
Valid Values:   true, false
Default:        false

allowCleartextPasswords=true allows using the cleartext client side plugin if required by an account, such as one defined with the PAM 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 include TLS / SSL, IPsec, or a private network.

Type:           bool
Valid Values:   true, false
Default:        false

allowFallbackToPlaintext=true acts like a --ssl-mode=PREFERRED MySQL client as described in Command Options for Connecting to the Server

Type:           bool
Valid Values:   true, false
Default:        true

allowNativePasswords=false disallows the usage of MySQL native password method.

Type:           bool
Valid Values:   true, false
Default:        false

allowOldPasswords=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.

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 fails. This enables for example support for utf8mb4 (introduced in MySQL 5.5.3) with fallback to utf8 for older servers (charset=utf8mb4,utf8).

See also Unicode Support.

Type:           bool
Valid Values:   true, false
Default:        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.

Type:           string
Valid Values:   <name>
Default:        utf8mb4_general_ci

Sets the collation used for client-server interaction on connection. In contrast to charset, 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 with SHOW 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 also Unicode Support.

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.

Type:           bool
Valid Values:   true, false
Default:        false

When columnsWithAlias is true, calls to sql.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 return u.id instead of just id if columnsWithAlias=true.

Type:           bool
Valid Values:   true, false
Default:        false

Toggles compression. false by default. Connections use zlib unless the optional github.com/block/mysql/zstd package is imported:

import _ "github.com/block/mysql/zstd"

This import also registers the MySQL driver. With compress=true (or EnableCompression(true)), connections automatically prefer zstd when the server supports it and fall back to zlib otherwise.

Applications that do not import mysql/zstd do not compile or link github.com/klauspost/compress. The optional package's dependency is listed in the module's go.mod.

Type:           bool
Valid Values:   true, false
Default:        false

If interpolateParams is true, placeholders (?) in calls to db.Query() and db.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 with interpolateParams=false.

This can not be used together with the multibyte encodings BIG5, CP932, GB2312, GBK or SJIS. These are rejected as they may introduce a SQL injection vulnerability!

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.

Note that this sets the location for time.Time values but does not change MySQL's time_zone setting. For that see the time_zone system variable, which can also be set as a DSN parameter.

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.

Type:           duration
Default:        0

Truncate time values in query arguments to the specified duration. The value must be a decimal number with a unit suffix ("ns", "us", "ms", etc...), such as "1us", "1ms", or "10ns".

[!NOTE] time.Time arguments are sent with up to nanosecond precision, so a value from time.Now() usually has more fractional-second digits than a DATETIME(N) or TIMESTAMP(N) column stores. On MariaDB, comparing such a value against an indexed column can prevent an index range scan, turning it into a full index scan. Truncating to the column's precision (1us for DATETIME(6)) avoids this. Only arguments sent to the server are truncated; values read from the server are not affected.

Type:           bool
Valid Values:   true, false
Default:        true

When tinyInt1IsBool=true, signed TINYINT(1) columns are treated as boolean values. Zero is returned as false, and non-zero values are returned as true. Their database type name is reported as BOOLEAN, and their scan type is bool for non-nullable columns or sql.NullBool for nullable columns.

Unsigned and ZEROFILL columns are not converted. Set tinyInt1IsBool=false to preserve the numeric TINYINT behavior.

Type:          decimal number
Default:       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 the max_allowed_packet variable from server on every connection.

Type:           bool
Valid Values:   true, false
Default:        false

Allow multiple statements in one query. This can be used to bach multiple queries. Use Rows.NextResultSet() to get result of the second and subsequent queries.

When multiStatements 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 using sql.Conn.Raw() and the mysql.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())
})

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 The date or datetime like 0000-00-00 00:00:00 is converted into zero value of time.Time.

Type:           duration
Default:        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".

Type:           bool
Valid Values:   true
Default:        (always on; see below)

Changed in this fork. Upstream makes this an option, defaulting to off. Here the driver always rejects read-only connections, Config.RejectReadOnly is gone, and the parameter survives only so a DSN written for upstream keeps parsing: rejectReadOnly=true is accepted and does nothing, while rejectReadOnly=false is an error rather than a silent no-op, because it states an expectation the driver will not meet.

Rejecting means that when a statement fails with a read-only error (1792, 1290 or 1836), the driver closes that connection and returns driver.ErrBadConn, so database/sql retries the statement on a new one.

It is not optional because the failure it prevents is silent and the mistake that causes it is invisible. RDS and Aurora fail over by moving DNS: a pooled connection to the demoted writer stays open and stays usable, and every write on it fails for as long as the pool keeps it — until the process restarts. Nothing in the DSN or in the error says the connection is the problem, and a deployment that forgot the option does not find out until a failover.

One exception: a transaction opened with sql.TxOptions{ReadOnly: true} is exempt. There the read-only error is the answer the caller asked for, and database/sql does not retry inside a transaction anyway, so rejecting would replace a usable *MySQLError with a dead transaction.

Two consequences worth knowing:

• A session made read-only by the application's own SET SESSION TRANSACTION READ ONLY is not exempt — nothing distinguishes it from a demoted writer. Writes on such a session are retried on a new connection instead of failing. Use privileges, or the ReadOnly transaction option, to express that intent.
• ERROR 1290 is also raised for conditions unrelated to failover — the ones you are likely to meet are secure_file_priv (a SELECT … INTO OUTFILE or LOAD DATA outside the permitted directory), super_read_only, innodb_read_only and --skip-grant-tables. All of these persist rather than clear, so the statement is retried, the connection churned, and the caller finally sees driver.ErrBadConn rather than the message that named the problem. The driver logs the server's own error before discarding it, so the condition is still identifiable — look for closing read-only connection in the log.

If your target is deliberately read-only — an Aurora reader endpoint, a replica, a source you only ever read from — this fork is a poor fit for that connection, and there is no longer an option to turn it off. Wrap reads in sql.TxOptions{ReadOnly: true} and they are exempt; anything on autocommit that the server rejects will still be retried and churned. If that is not workable, use a driver that lets you disable the behaviour for that connection. The trade is deliberate: the population this fork serves writes to RDS primaries, where the silent failure is the more expensive one.

Type:           string
Valid Values:   <name>
Default:        none

Server public keys can be registered with mysql.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.

Type:           duration
Default:        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".

Type:           bool / string
Valid Values:   true, false, skip-verify, preferred, <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) or use preferred to use TLS only when advertised by the server. This is similar to skip-verify, but additionally allows a fallback to a connection which is not encrypted. Neither skip-verify nor preferred add any reliable security. You can use a custom TLS config after registering it with mysql.RegisterTLSConfig.

Type:           duration
Default:        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".

Type:           comma-delimited string of user-defined "key:value" pairs
Valid 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 be url.QueryEscape'ed! (which implies values of string variables must be wrapped with %27).
• System variables are set and retained by FormatDSN in the order they appear in the DSN. Use Config.Apply(AddParam(name, value)) to preserve order when adding them programmatically.

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 variable sql_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@/

Verifying Server

With system trust roots, use tls=true to verify the certificate chain and the server name in the connection address. When dialing an IP for a DNS-named server, set the expected name explicitly:

cfg.TLS = &tls.Config{ServerName: "database.example"}

Private CA (VERIFY_CA)

For an exclusive private CA or the intended server's self-signed certificate, verify the certificate chain without checking the server name:

roots := x509.NewCertPool()
if !roots.AppendCertsFromPEM(caPEM) { // Obtain the trusted certificate through a trusted channel.
    return errors.New("no CA certificates found")
}
cfg.TLS = &tls.Config{
    InsecureSkipVerify: true, // Replace default verification with VERIFY_CA below.
    VerifyConnection: func(state tls.ConnectionState) error {
        if len(state.PeerCertificates) == 0 {
            return errors.New("server did not provide a certificate")
        }
        intermediates := x509.NewCertPool()
        for _, cert := range state.PeerCertificates[1:] {
            intermediates.AddCert(cert)
        }
        _, err := state.PeerCertificates[0].Verify(x509.VerifyOptions{
            Roots:         roots,
            Intermediates: intermediates,
            KeyUsages:     []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
            // Omit DNSName for VERIFY_CA.
        })
        return err
    },
}

This safely authenticates the intended server without hostname verification when the trusted signing key is kept private and has not issued certificates to other users or unrelated servers. A CA shared with unrelated services does not provide that guarantee. InsecureSkipVerify plus RootCAs alone does not verify certificates; keep the callback and propagate its errors.

Pass cfg to mysql.NewConnector and sql.OpenDB. For DSNs, register the TLS configuration with mysql.RegisterTLSConfig and use its name in tls. Avoid tls=skip-verify, tls=preferred, and AllowFallbackToPlaintext when server authentication is required. See Go's tls.Config.

OpenID Connect authentication

Use cfg.Apply(mysql.OIDCToken(token)) with mysql.NewConnector and sql.OpenDB. The token is not included in FormatDSN; there is no OIDC DSN parameter. Configure TLS to authenticate the intended server. If using InsecureSkipVerify, provide proper replacement verification; the driver does not validate your policy. Plaintext fallback and TLS provided solely by a custom dialer are not supported.

To obtain a fresh token for each new connection:

cfg := mysql.NewConfig()
cfg.User = "oidc_user"
cfg.Addr = "database.example:3306"
cfg.TLS = &tls.Config{ServerName: "database.example"}
if err := cfg.Apply(mysql.BeforeConnect(func(ctx context.Context, cfg *mysql.Config) error {
    token, err := tokenSource(ctx) // Application-provided, safe for concurrent calls.
    if err != nil {
        return err
    }
    return cfg.Apply(mysql.OIDCToken(token))
})); err != nil {
    return err
}
connector, err := mysql.NewConnector(cfg)
if err != nil {
    return err
}
db := sql.OpenDB(connector)
defer db.Close()

An empty token makes Apply return ErrOpenIDConnectToken without changing the configuration. Return this error from BeforeConnect to abort the connection. Token refresh affects new connections, not existing pooled sessions.

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 the database/sql documentation. The read, write, and dial timeouts for each individual connection are configured with the DSN parameters readTimeout, writeTimeout, and timeout, respectively.

ColumnType Support

This driver supports the ColumnType interface introduced in Go 1.8, with the exception of ColumnType.Length(), which is currently not supported. All Unsigned database type names will be returned UNSIGNED with INT, TINYINT, SMALLINT, MEDIUMINT, BIGINT.

context.Context Support

Go 1.8 added database/sql support for context.Context. This driver supports query timeouts and cancellation via contexts. See context support in the database/sql package for more details.

[!IMPORTANT] The QueryContext, ExecContext, etc. variants provided by database/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.

Authentication Plugin System

The driver implements a pluggable authentication system that supports various authentication methods used by MySQL and MariaDB servers. The built-in authentication plugins include:

• mysql_native_password - Legacy MySQL authentication and the driver's initial fallback
• caching_sha2_password - Default authentication method in MySQL 8.0+
• mysql_clear_password - Cleartext authentication (requires allowCleartextPasswords=true)
• mysql_old_password - Old MySQL authentication (requires allowOldPasswords=true)
• sha256_password - SHA256 authentication
• client_ed25519 - MariaDB Ed25519 authentication

Custom plugins implement the two methods of AuthPlugin, InitAuth and ContinuationAuth, and are registered with RegisterAuthPlugin(name, factory). Registration does not call the factory; the driver calls it to create an independent instance for each authentication exchange. Factories may run concurrently for different connections. All built-in plugins use the same registry: registering a built-in name replaces its factory for subsequent authentication exchanges, including the initial handshake and authentication switches. Authentication-method permissions such as allowCleartextPasswords still apply to that name. Built-in plugin implementations are internal to the driver.

The driver passes the connection's context.Context for cancellation and an AuthContext snapshot containing the selected credentials, established transport information, and configured RSA public key. Plugins do not receive or modify the connection's Config; the driver checks authentication-method permissions before starting a plugin. Custom plugins that require a particular transport must check it in InitAuth before returning credentials.

AuthContext.TLS() reports a completed MySQL TLS handshake, not merely a TLS configuration or an external tunnel. A continuation returning nil, nil waits for another server packet without sending; a non-nil empty slice sends an empty packet. Authentication succeeds only when the driver receives the server's OK packet.

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/block/mysql"

Files must be explicitly allowed by registering them with mysql.RegisterLocalFile(filepath) (recommended) or the allowlist 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. Choose different names for different handlers and DeregisterReaderHandler when you don't need it anymore.

See the godoc of this fork 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 program.

However, many want to scan MySQL DATE and DATETIME values into time.Time variables, which is the logical equivalent 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.

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 the charset or collation DSN parameter.

• When only the charset is specified, the SET NAMES <charset> query is sent and the server's default collation is used.
• When both the charset and collation are specified, the SET NAMES <charset> COLLATE <collation> query is sent.
• When only the collation is specified, the collation is specified in the protocol handshake and the SET 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.

See http://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 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 and commercially.
• When distributing, 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).
• You needn't publish the source code of your library as long as the files licensed under the MPL 2.0 are unchanged.

Please read the MPL 2.0 FAQ if you have further questions regarding the license.

You can read the full terms here: LICENSE.