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.

This particular version uses github.com/jmoiron/sqlx. Not all methods are implemented, but extending this is simple.

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() (*sqlx.Tx, error)
  • func (db *DB) BeginTx(ctx context.Context, opts *sql.TxOptions) (*sqlx.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() *sqlx.DB
  • func (db *DB) Ping() error
  • func (db *DB) PingContext(ctx context.Context) error
  • func (db *DB) Preparex(query string) (*sqlx.Stmt, error)
  • func (db *DB) PreparexContext(ctx context.Context, query string) (*sqlx.Stmt, error)
  • func (db *DB) PreparexSlave(query string) (*sqlx.Stmt, error)
  • func (db *DB) PreparexSlaveContext(ctx context.Context, query string) (*sqlx.Stmt, error)
  • func (db *DB) QueryxSlave(query string, args ...interface{}) (*sqlx.Rows, error)
  • func (db *DB) QueryxSlaveContext(ctx context.Context, query string, args ...interface{}) (*sqlx.Rows, error)
  • func (db *DB) Select(dest interface{}, query string, args ...interface{}) error
  • func (db *DB) SelectContext(ctx context.Context, dest interface{}, query string, args ...interface{}) error
  • func (db *DB) SetConnMaxLifetime(d time.Duration)
  • func (db *DB) SetMaxIdleConns(n int)
  • func (db *DB) SetMaxOpenConns(n int)
  • func (db *DB) Slave() *sqlx.DB
• type Stmt

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

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() (*sqlx.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) (*sqlx.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() *sqlx.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) Preparex

func (db *DB) Preparex(query string) (*sqlx.Stmt, error)

Preparex prepares a statement that connects to the master.

func (*DB) PreparexContext

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

func (*DB) PreparexSlave

func (db *DB) PreparexSlave(query string) (*sqlx.Stmt, error)

PreparexSlave prepares a statement that connects with one of the slaves.

func (*DB) PreparexSlaveContext

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

func (*DB) QueryxSlave

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

QueryxSlave performs an sqlx Queryx call against one of the slaves.

func (*DB) QueryxSlaveContext

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

func (*DB) Select

func (db *DB) Select(dest interface{}, query string, args ...interface{}) error

Select performs a sqlx select against one of the slaves.

func (*DB) SelectContext

func (db *DB) SelectContext(ctx context.Context, dest interface{}, query string, args ...interface{}) error

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() *sqlx.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.