nap

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.

Nap requires Go version 1.8 or greater.

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

See LICENSE

Documentation

Index

• type DB
  • func Open(driverName, dataSourceNames string) (*DB, error)
  • func (db *DB) Begin() (*sql.Tx, error)
  • func (db *DB) BeginTx(ctx context.Context, opts *sql.TxOptions) (*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) ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
  • func (db *DB) Master() *sql.DB
  • func (db *DB) Ping() error
  • func (db *DB) PingContext(ctx context.Context) error
  • func (db *DB) Prepare(query string) (Stmt, error)
  • func (db *DB) PrepareContext(ctx context.Context, query string) (Stmt, error)
  • func (db *DB) Query(query string, args ...interface{}) (*sql.Rows, error)
  • func (db *DB) QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)
  • func (db *DB) QueryRow(query string, args ...interface{}) *sql.Row
  • func (db *DB) QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row
  • func (db *DB) SetConnMaxLifetime(d time.Duration)
  • func (db *DB) SetMaxIdleConns(n int)
  • func (db *DB) SetMaxOpenConns(n int)
  • func (db *DB) Slave() *sql.DB
• type Stmt

Types

type DB

type DB struct {
	Pdbs  []*sql.DB // Physical databases
	Count uint64    // Monotonically incrementing counter on each query
}

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

func Open(driverName, dataSourceNames string) (*DB, error)

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

func (db *DB) Begin() (*sql.Tx, error)

Begin starts a transaction on the master. The isolation level is dependent on the driver.

func (*DB) BeginTx

func (db *DB) BeginTx(ctx context.Context, opts *sql.TxOptions) (*sql.Tx, error)

BeginTx starts a transaction with the provided context on the master.

The provided TxOptions is optional and may be nil if defaults should be used. If a non-default isolation level is used that the driver doesn't support, an error will be returned.

func (*DB) Close

func (db *DB) Close() error

Close closes all physical databases concurrently, releasing any open resources.

func (*DB) Driver

func (db *DB) Driver() driver.Driver

Driver returns the physical database's underlying driver.

func (*DB) Exec

func (db *DB) Exec(query string, args ...interface{}) (sql.Result, error)

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) ExecContext

func (db *DB) ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)

ExecContext 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) Master

func (db *DB) Master() *sql.DB

Master returns the master physical database

func (*DB) Ping

func (db *DB) Ping() error

Ping verifies if a connection to each physical database is still alive, establishing a connection if necessary.

func (*DB) PingContext

func (db *DB) PingContext(ctx context.Context) error

PingContext verifies if a connection to each physical database is still alive, establishing a connection if necessary.

func (*DB) Prepare

func (db *DB) Prepare(query string) (Stmt, error)

Prepare creates a prepared statement for later queries or executions on each physical database, concurrently.

func (*DB) PrepareContext

func (db *DB) PrepareContext(ctx context.Context, query string) (Stmt, error)

PrepareContext creates a prepared statement for later queries or executions on each physical database, concurrently.

The provided context is used for the preparation of the statement, not for the execution of the statement.

func (*DB) Query

func (db *DB) Query(query string, args ...interface{}) (*sql.Rows, error)

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) QueryContext

func (db *DB) QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)

QueryContext executes a query that returns rows, typically a SELECT. The args are for any placeholder parameters in the query. QueryContext uses a slave as the physical db.

func (*DB) QueryRow

func (db *DB) QueryRow(query string, args ...interface{}) *sql.Row

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) QueryRowContext

func (db *DB) QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row

QueryRowContext executes a query that is expected to return at most one row. QueryRowContext always return a non-nil value. Errors are deferred until Row's Scan method is called. QueryRowContext uses a slave as the physical db.

func (*DB) SetConnMaxLifetime

func (db *DB) SetConnMaxLifetime(d time.Duration)

SetConnMaxLifetime sets the maximum amount of time a connection may be reused. Expired connections may be closed lazily before reuse. If d <= 0, connections are reused forever.

func (*DB) SetMaxIdleConns

func (db *DB) SetMaxIdleConns(n int)

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

func (db *DB) SetMaxOpenConns(n int)

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).

func (*DB) Slave

func (db *DB) Slave() *sql.DB

Slave returns one of the physical databases which is a slave

type Stmt

type Stmt interface {
	Close() error
	Exec(...interface{}) (sql.Result, error)
	Query(...interface{}) (*sql.Rows, error)
	QueryRow(...interface{}) *sql.Row
}

Stmt is an aggregate prepared statement. It holds a prepared statement for each underlying physical db.