README
¶
Nap
Nap is a library that abstracts access to master-slave physical SQL servers topologies as a single logical database mimicking the standard sql.DB APIs.
Install
$ go get github.com/tsenart/nap
Usage
package main
import (
"log"
"github.com/tsenart/nap"
_ "github.com/go-sql-driver/mysql" // Any sql.DB works
)
func main() {
// The first DSN is assumed to be the master and all
// other to be slaves
dsns := "tcp://user:password@master/dbname;"
dsns += "tcp://user:password@slave01/dbname;"
dsns += "tcp://user:password@slave02/dbname"
db, err := nap.Open("mysql", dsns)
if err != nil {
log.Fatal(err)
}
if err := db.Ping(); err != nil {
log.Fatalf("Some physical database is unreachable: %s", err)
}
// Read queries are directed to slaves with Query and QueryRow.
// Always use Query or QueryRow for SELECTS
// Load distribution is round-robin only for now.
var count int
err = db.QueryRow("SELECT COUNT(*) FROM sometable").Scan(&count)
if err != nil {
log.Fatal(err)
}
// Write queries are directed to the master with Exec.
// Always use Exec for INSERTS, UPDATES
err = db.Exec("UPDATE sometable SET something = 1")
if err != nil {
log.Fatal(err)
}
// Prepared statements are aggregates. If any of the underlying
// physical databases fails to prepare the statement, the call will
// return an error. On success, if Exec is called, then the
// master is used, if Query or QueryRow are called, then a slave
// is used.
stmt, err := db.Prepare("SELECT * FROM sometable WHERE something = ?")
if err != nil {
log.Fatal(err)
}
// Transactions always use the master
tx, err := db.Begin()
if err != nil {
log.Fatal(err)
}
// Do something transactional ...
if err = tx.Commit(); err != nil {
log.Fatal(err)
}
// If needed, one can access the master or a slave explicitly.
master, slave := db.Master(), db.Slave()
}
Todo
- Support other slave load balancing algorithms.
License
The MIT License (MIT)
Copyright (c) 2013 Tomás Senart
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Documentation
¶
Index ¶
- type DB
- func (db *DB) Begin() (*sql.Tx, error)
- func (db *DB) Close() error
- func (db *DB) Driver() driver.Driver
- func (db *DB) Exec(query string, args ...interface{}) (sql.Result, error)
- func (db *DB) Master() *sql.DB
- func (db *DB) Ping() error
- func (db *DB) Prepare(query string) (Stmt, error)
- func (db *DB) Query(query string, args ...interface{}) (*sql.Rows, error)
- func (db *DB) QueryRow(query string, args ...interface{}) *sql.Row
- func (db *DB) SetMaxIdleConns(n int)
- func (db *DB) SetMaxOpenConns(n int)
- func (db *DB) Slave() *sql.DB
- type Stmt
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB is a logical database with multiple underlying physical databases forming a single master multiple slaves topology. Reads and writes are automatically directed to the correct physical db.
func Open ¶
Open concurrently opens each underlying physical db. dataSourceNames must be a semi-comma separated list of DSNs with the first one being used as the master and the rest as slaves.
func (*DB) Begin ¶
Begin starts a transaction on the master. The isolation level is dependent on the driver.
func (*DB) Exec ¶
Exec executes a query without returning any rows. The args are for any placeholder parameters in the query. Exec uses the master as the underlying physical db.
func (*DB) Ping ¶
Ping verifies if a connection to each physical database is still alive, establishing a connection if necessary.
func (*DB) Prepare ¶
Prepare creates a prepared statement for later queries or executions on each physical database, concurrently.
func (*DB) Query ¶
Query executes a query that returns rows, typically a SELECT. The args are for any placeholder parameters in the query. Query uses a slave as the physical db.
func (*DB) QueryRow ¶
QueryRow executes a query that is expected to return at most one row. QueryRow always return a non-nil value. Errors are deferred until Row's Scan method is called. QueryRow uses a slave as the physical db.
func (*DB) SetMaxIdleConns ¶
SetMaxIdleConns sets the maximum number of connections in the idle connection pool for each underlying physical db. If MaxOpenConns is greater than 0 but less than the new MaxIdleConns then the new MaxIdleConns will be reduced to match the MaxOpenConns limit If n <= 0, no idle connections are retained.
func (*DB) SetMaxOpenConns ¶
SetMaxOpenConns sets the maximum number of open connections to each physical database. If MaxIdleConns is greater than 0 and the new MaxOpenConns is less than MaxIdleConns, then MaxIdleConns will be reduced to match the new MaxOpenConns limit. If n <= 0, then there is no limit on the number of open connections. The default is 0 (unlimited).
Source Files