mysql

Documentation

Overview

Go MySQL Driver - 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")

See https://github.com/go-sql-driver/mysql#usage for details

Index

• Variables
• func DeregisterLocalFile(filePath string)
• func DeregisterReaderHandler(name string)
• func DeregisterTLSConfig(key string)
• func RegisterDial(net string, dial DialFunc)
• func RegisterLocalFile(filePath string)
• func RegisterReaderHandler(name string, handler func() io.Reader)
• func RegisterTLSConfig(key string, config *tls.Config) error
• func SetLogger(logger Logger) error
• type DialFunc
• type Logger
• type MySQLDriver
  • func (d MySQLDriver) Open(dsn string) (driver.Conn, error)
• type MySQLError
  • func (me *MySQLError) Error() string
• type MySQLWarning
• type MySQLWarnings
  • func (mws MySQLWarnings) Error() string
• type NullTime
  • func (nt *NullTime) Scan(value interface{}) (err error)
  • func (nt NullTime) Value() (driver.Value, error)

Variables

var (
	ErrInvalidConn       = errors.New("Invalid Connection")
	ErrMalformPkt        = errors.New("Malformed Packet")
	ErrNoTLS             = errors.New("TLS encryption requested but server does not support TLS")
	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")
	ErrCleartextPassword = errors.New("This user requires clear text authentication. If you still want to use it, please add 'allowCleartextPasswords=1' to your DSN.")
	ErrUnknownPlugin     = errors.New("The 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. You can change this value on the server by adjusting the 'max_allowed_packet' variable.")
	ErrBusyBuffer        = errors.New("Busy buffer")
)

Various errors the driver might return. Can change between driver versions.

Functions

func DeregisterLocalFile

func DeregisterLocalFile(filePath string)

DeregisterLocalFile removes the given filepath from the whitelist.

func DeregisterReaderHandler

func DeregisterReaderHandler(name string)

DeregisterReaderHandler removes the ReaderHandler function with the given name from the registry.

func DeregisterTLSConfig

func DeregisterTLSConfig(key string)

DeregisterTLSConfig removes the tls.Config associated with key.

func RegisterDial

func RegisterDial(net string, dial DialFunc)

RegisterDial registers a custom dial function. It can then be used by the network address mynet(addr), where mynet is the registered new network. addr is passed as a parameter to the dial function.

func RegisterLocalFile

func RegisterLocalFile(filePath string)

RegisterLocalFile adds the given file to the file whitelist, so that it can be used by "LOAD DATA LOCAL INFILE <filepath>". Alternatively you can allow the use of all local files with the 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 {
...

func RegisterReaderHandler

func RegisterReaderHandler(name string, handler func() io.Reader)

RegisterReaderHandler registers a handler function which is used to 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 the request is finished.

mysql.RegisterReaderHandler("data", func() io.Reader {
	var csvReader io.Reader // Some Reader that returns CSV data
	... // Open Reader here
	return csvReader
})
err := db.Exec("LOAD DATA LOCAL INFILE 'Reader::data' INTO TABLE foo")
if err != nil {
...

func RegisterTLSConfig

func RegisterTLSConfig(key string, config *tls.Config) error

RegisterTLSConfig registers a custom tls.Config to be used with sql.Open. Use the key as a value in the DSN where tls=value.

rootCertPool := x509.NewCertPool()
pem, err := ioutil.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")

func SetLogger

func SetLogger(logger Logger) error

SetLogger is used to set the logger for critical errors. The initial logger is os.Stderr.

Types

type DialFunc

type DialFunc func(addr string) (net.Conn, error)

DialFunc is a function which can be used to establish the network connection. Custom dial functions must be registered with RegisterDial

type Logger

type Logger interface {
	Print(v ...interface{})
}

Logger is used to log critical error messages.

type MySQLDriver

type MySQLDriver struct{}

This struct is exported to make the driver directly accessible. In general the driver is used via the database/sql package.

func (MySQLDriver) Open

func (d MySQLDriver) Open(dsn string) (driver.Conn, error)

Open new Connection. See https://github.com/go-sql-driver/mysql#dsn-data-source-name for how the DSN string is formated

type MySQLError

type MySQLError struct {
	Number  uint16
	Message string
}

MySQLError is an error type which represents a single MySQL error

func (*MySQLError) Error

func (me *MySQLError) Error() string

type MySQLWarning

type MySQLWarning struct {
	Level   string
	Code    string
	Message string
}

MySQLWarning is an error type which represents a single MySQL warning. Warnings are returned in groups only. See MySQLWarnings

type MySQLWarnings

type MySQLWarnings []MySQLWarning

MySQLWarnings is an error type which represents a group of one or more MySQL warnings

func (MySQLWarnings) Error

func (mws MySQLWarnings) Error() string

type NullTime

type NullTime struct {
	Time  time.Time
	Valid bool // Valid is true if Time is not NULL
}

NullTime represents a time.Time that may be NULL. NullTime implements the Scanner interface so it can be used as a scan destination:

var nt NullTime
err := 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

func (*NullTime) Scan

func (nt *NullTime) Scan(value interface{}) (err error)

Scan implements the Scanner interface. The value type must be time.Time or string / []byte (formatted time-string), otherwise Scan fails.

func (NullTime) Value

func (nt NullTime) Value() (driver.Value, error)

Value implements the driver Valuer interface.