morphling

README

Morphling

Morphling is a SQL wrapper for database replication topology. Morphling helps you to determine which connection to be used when execute query to the sql database. It's not an ORM

Why you need morphling ? Golang sql package is allowed you to open multiple connection, but without any restriction, means any connection you opened, can do all SQL manipulation (insert, update, delete, select), While slave database supposed to be only allowed to do select , with morphling it manage the master slave connection usage.

Why morphling can only specify one replica ? We can use load balancer such as HAProxy or else to handle a replica set, its provide abstraction to how you want to handle your replica sets load, either round robin or else.

Example

package main

import (
    "fmt"
    "github.com/ahartanto/morphling"
    _ "github.com/go-sql-driver/mysql"
)

func main() {

    var urlFormat = "%s:%s@tcp(%s:%d)/%s?charset=%s&parseTime=true&loc=Local"

    // Prepare data source for master connection
    masterUser := "user"
    masterPassword := "password"
    masterHost := "masterhost"
    masterPort := "3306"
    masterDBName := "dbname"
    masterCharset := "utf8"
    dataSourceMaster := fmt.Sprintf(urlFormat, masterUser, masterPassword,masterHost, masterPort, masterDBName, masterCharset)

    // Prepare data source for slave connection
    slaveUser := "user"
    slavePassword := "password"
    slaveHost := "slavehost"
    slavePort := "3306"
    slaveDBName := "dbname"
    slaveCharset := "utf8"
    dataSourceSlave := fmt.Sprintf(urlFormat, slaveUser, slavePassword,slaveHost, slavePort, slaveDBName, slaveCharset)

    // Get database handler
    db, err := morphling.OpenConnection(morphling.MySQLDriver, dataSourceMaster, dataSourceSlave)
    if err != nil {
        panic(fmt.Errorf("failed dial database : %v", err))
    }

    // Then you can do the query as golang sql package does
    var id int
    q := fmt.Sprintf("SELECT id FROM accounts LIMIT 1")
    err = db.QueryRow(q).Scan(&id)
    fmt.Printf(id)

}

About

Fun fact, Morphling is a ranged agility dota hero that has many flexible abilities. His ultimate, Morph, transforms him into a copy of an enemy using their stats and basic abilities.

Morphling can be as an analogy of database replication, select / read data is a basic abilites that replica has, while insert, update and delete is the main abilites.

Documentation

Index

• Variables
• type DB
  • func Open(driverName, dataSourceMainStr, dataSourceReplicaStr string) (*DB, error)
  • func (m *DB) Begin() (*sql.Tx, error)
  • func (m *DB) BeginTx(ctx context.Context, opts *sql.TxOptions) (*sql.Tx, error)
  • func (m *DB) Close() error
  • func (m *DB) Exec(query string, args ...interface{}) (sql.Result, error)
  • func (m *DB) Ping() error
  • func (m *DB) Prepare(query string) (*sql.Stmt, error)
  • func (m *DB) Query(query string, args ...interface{}) (*sql.Rows, error)
  • func (m *DB) QueryRow(query string, args ...interface{}) *sql.Row
  • func (m *DB) SetConnMaxLifetime(d time.Duration)
  • func (m *DB) SetMaxIdleConns(n int)
  • func (m *DB) SetMaxOpenConns(n int)

Variables

var (
	MySQLDriver = "mysql"
)

Types

type DB

type DB struct {
	// contains filtered or unexported fields
}

DB is logical database object with main as master physical database and replica as slave database with loadbalancer

func Open

func Open(driverName, dataSourceMainStr, dataSourceReplicaStr string) (*DB, error)

Open opens master and slave database connection

func (*DB) Begin

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

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

func (*DB) BeginTx

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

BeginTx starts a transaction. The provided context is used until the transaction is committed or rolled back. If the context is canceled, the sql package will roll back the transaction. Tx.Commit will return an error if the context provided to BeginTx is canceled. 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 (m *DB) Close() error

Close closes all database, releasing any open resources.

It is rare to Close a DB, as the DB handle is meant to be long-lived and shared between many goroutines.

func (*DB) Exec

func (m *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.

func (*DB) Ping

func (m *DB) Ping() error

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

func (*DB) Prepare

func (m *DB) Prepare(query string) (*sql.Stmt, error)

Prepare creates a prepared statement for later queries or executions. Multiple queries or executions may be run concurrently from the returned statement. The caller must call the statement's Close method when the statement is no longer needed.

func (*DB) Query

func (m *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.

func (*DB) QueryRow

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

QueryRow executes a query that is expected to return at most one row. QueryRow always returns a non-nil value. Errors are deferred until Row's Scan method is called.

func (*DB) SetConnMaxLifetime

func (m *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 (m *DB) SetMaxIdleConns(n int)

SetMaxIdleConns sets the maximum number of connections in the idle connection pool.

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 (m *DB) SetMaxOpenConns(n int)

SetMaxOpenConns sets the maximum number of open connections to the 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).