README
¶
Golang SQL driver for Amazon MySQL RDS which supports replica load balanacing
Install
go get -u github.com/pinpt/rdsmysql
Overview
The goal of this driver is to support Amazon RDS load balancing for MySQL and is most effective when RDS is configured to auto scale in and out.
Queries are transparently split to the master vs the replica based on the method used against the sql.DB.
All Exec, ExecContext or Begin transactions will be issued against the master host.
All Query, QueryRow, QueryContext, QueryRowContext queries will be issued against a replica picked at random (if more than 1 replica available).
When the Database is opened, the driver will (in the background) monitor replica changes in RDS using the information_schema.replica_host_status table. When RDS is setup to auto scale in and out, the driver will keep track of these changes and load balance queries across them as the replicas change. If no replica is available, the master host will be used instead.
Usage
Use it like a normal MySQL driver except instead of mysql use rdsmysql and use the hostname to the RDS cluster as the url.
For example, if your RDS cluster was foo-bar-rds-cluster.cluster-acddd9x9x9.us-east-1.rds.amazonaws.com, you would use:
db, err := sql.Open("rdsmysql", "myuser:somepass@foo-bar-rds-cluster.cluster-acddd9x9x9.us-east-1.rds.amazonaws.com:3306/mydb")
In the above example, we used the username mysuser with a password of somepass and selected the database named mydb.
You can add any additional mysql driver options as normal query parameters. By default, TLS will be properly set to the RDS TLS certificates.
The following are optional query parameters to tune the driver:
max-time-leaving: specifies how often the client should query the sql server for current servers list. defaults to 30sfail-duration: the delay after node was removed from replica_host_status or query failed and db.Close is called. Also required for long running queries to allow interrupting iterating rows. shorter time cleans up resources faster. longer time reuses db instance and connection for temporary errors. defaults to 180supdate-duration: the duration the node is marked as failed after failing query. The node is ignored for this duration. shorter time re-connects faster for restarts and temporary errors. longer time avoids unnecessary re-tries for shutdowns. defaults to 240s
You can set debug logging by implementing the Logger interface and setting it to the L public package variable.
License
All of this code is Copyright © 2018-2019 by Pinpoint Software, Inc. Licensed under the MIT License
Documentation
¶
Overview ¶
Package rdsmysql provides load balancing of read-only queries across multiple database instances. Designed to work with AWS RDS Aurora read slaves auto-scaling.
Details ¶
- queries information_schema.replica_host_status table discovering new or removing no longer available replicas
- supports replica restarts and deletes, retries connections failed this way against a different instance
- does not retry queries that failed in progress (due to hard server shutdowns, network interruptions)
Index ¶
Constants ¶
const DriverName = "rdsmysql"
DriverName is the public name of the driver
const MaxConnectAttempts = 5
MaxConnectAttempts is the max number of tries to connect to a server
const MaxServersTriedForQuery = 3
MaxServersTriedForQuery is the max number of servers tried for a query. The actual number of retries is +1 since it tries to connect to initial instance twice.
Variables ¶
var DefaultDriverOpts = url.Values{
"collation": {"utf8mb4_unicode_ci"},
"parseTime": {"true"},
"autocommit": {"true"},
"timeout": {defaultConnectTimeout.String()},
"readTimeout": {defaultReadimeout.String()},
}
DefaultDriverOpts are the default driver values if not provided in the DSN
var ErrConnectMaxRetriesExceeded = errors.New("tried MaxServersTriedForQuery servers to connect, all failed")
ErrConnectMaxRetriesExceeded is returned from Query when query tried more than MaxServersTriedForQuery servers, and all of them failed. There could be more available instances.
var ErrExecMaxRetriesExceeded = errors.New("max retries exceeded for retryable error")
ErrExecMaxRetriesExceeded is returned after exhausting a retryable query
var ErrNoServersAvailable = errors.New("no servers available")
ErrNoServersAvailable is returned from Query when no servers are available. All servers returned from information_schema.replica_host_status failed.
var ErrUnsupportedMethod = errors.New("unsupported method")
ErrUnsupportedMethod is returned for an unsupported method that is invoked against the underlying driver
var MaxRetries = 3
MaxRetries is the max number of times that a deadlock query will be retried
Functions ¶
Types ¶
type Logger ¶
type Logger interface {
Log(keyvals ...interface{}) error
}
Logger is the fundamental interface for all log operations. Log creates a log event from keyvals, a variadic sequence of alternating keys and values. Implementations must be safe for concurrent use by multiple goroutines. In particular, any implementation of Logger that appends to keyvals or modifies or retains any of its elements must make a copy first.
var L Logger = &defaultLogger{}
L is the logger to use internally by the package, defaults to a logger which is no op
type TrackedConn ¶
type TrackedConn interface {
// Terminate will forceably shutdown the connection and close all db
Terminate()
}
TrackedConn is an interface that the conn implementation returned from the Open returns to allow it to be terminated
Source Files
Directories