README
¶
This is a project I started to see what would be required to create a database/sql driver for the MySQL X protocol which was announced as part of the MySQL 5.7.12 server release. Documentation of the MySQL X protocol can be found here: https://dev.mysql.com/doc/internals/en/x-protocol.html. The code in this project is based very heavily on the original MySQL driver which was available on https://github.com/go-sql-driver/mysql as of the time that the MySQL X protocol was announced. Copyright (C) 2016 Simon J Mudd <sjmudd@pobox.com> KNOWN ISSUES ============ This file lists the current known issues with the driver where I have bothered to find them. They can be split into the following types: [A] Issues with the driver itself --------------------------------- A1. Use of TLS mode is not possible yet if the appropriate seting is provided with the DSN. A2. No way to determine mysqlx_max_allowed_packet short of doing a full query after authorisation. This will add several round trips to the connection to get this information and is needed to set internal buffers but to also to prevent sending "too large packets" to the server. A3. No way to provide parameters to SQL queries A4. Support of understanding all datatypes is incomplete A5. Documentation of the mapping of the MySQL datatypes to the value provided back to the caller is not done. This is actually quite important to ensure that behavour is clearly defined. A6. No character set support. The X protocol is also rather vague about expectations for client and server initial setups which does not help. However some character data that's received from the MySQL server may require conversion to Go's utf8 etc and that is not done as the Go driver does not expose the server's internal datatypes. [B] Issues with using the X protocol using github.com/golang/go-sql-driver because the driver does not support the functionality needed by X protocol or expose them to the client. --------------------------------- B1. No way to disconnect a session and re-authenticate, allowed by X protocol but not by go driver. Close() is likely to drop the connection to ensure that previous state does not remain in the "previous connection". B2. No way to determine capabilities prior to logging in. Perhaps not critical but not currently possible. X protocol allows this which may be convenient. B3. No way to use the XAPI type JSON/document store interface. This probably makes sense as database/sql assumes you're going to talk SQL. B4. No way to pipeline commands. You must wait for a single statement to complete prior to sending the next one. The pool functionality of the go driver would allow you to use another connection transparently but that's not the same. B5. No way to change TLS setting once connected. The attribute is a connection setting and while it may not be common to want to change behaviour it might be convenient. B6. No support for anything like init_connect which can be used frequently. I think really this should be negoatiated as part of the X protocol but that functionality is not currently present.
Documentation
¶
Index ¶
- Constants
- Variables
- func DeregisterTLSConfig(key string)
- func RegisterDial(net string, dial DialFunc)
- func RegisterTLSConfig(key string, config *tls.Config) error
- type DialFunc
- type MySQL41
- type NullTime
- type ServerCapabilities
- func (sc ServerCapabilities) AddArrayString(name string, values []string) error
- func (sc ServerCapabilities) AddScalarBool(name string, value bool) error
- func (sc ServerCapabilities) AddScalarString(name string, value string) error
- func (sc ServerCapabilities) Exists(name string) bool
- func (sc ServerCapabilities) Values(name string) Values
- type Values
- type XDriver
Constants ¶
View Source
const ( // CapabilityString is a string CapabilityString capabilityType = iota // CapabilityBool is a boolean CapabilityBool )
Variables ¶
View Source
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 DeregisterTLSConfig ¶
func DeregisterTLSConfig(key string)
DeregisterTLSConfig removes the tls.Config associated with key.
func RegisterDial ¶
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 RegisterTLSConfig ¶
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")
Types ¶
type DialFunc ¶
DialFunc is a function which can be used to establish the network connection. Custom dial functions must be registered with RegisterDial
type MySQL41 ¶
type MySQL41 struct {
// contains filtered or unexported fields
}
MySQL41 manages the MySQL41 authentication protocol
func NewMySQL41 ¶
NewMySQL41 returns a pointer to an initialised MySQL41 struct
func (*MySQL41) GetInitialAuthData ¶
GetInitialAuthData returns any initial authentication data
func (*MySQL41) GetNextAuthData ¶
GetNextAuthData returns data db + name + encrypted hash
type NullTime ¶
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
type ServerCapabilities ¶
ServerCapabilities is a named map of capability values
func (ServerCapabilities) AddArrayString ¶
func (sc ServerCapabilities) AddArrayString(name string, values []string) error
AddArrayString adds the given array of strings to the named capability
func (ServerCapabilities) AddScalarBool ¶
func (sc ServerCapabilities) AddScalarBool(name string, value bool) error
AddScalarBool adds the given boolean value to the named capability
func (ServerCapabilities) AddScalarString ¶
func (sc ServerCapabilities) AddScalarString(name string, value string) error
AddScalarString adds the given string value to the named capability
func (ServerCapabilities) Exists ¶
func (sc ServerCapabilities) Exists(name string) bool
Exists returns true if the named capability exists
func (ServerCapabilities) Values ¶
func (sc ServerCapabilities) Values(name string) Values
Values returns the named Values
Source Files
Click to show internal directories.
Click to hide internal directories.