sqalx

README

sqalx

sqalx (pronounced 'scale-x') is a library built on top of sqlx that allows to seamlessly create nested transactions and to avoid thinking about whether or not a function is called within a transaction. With sqalx you can easily create reusable and composable functions that can be called within or out of transactions and that can create transactions themselves.

Getting started

$ go get github.com/heetch/sqalx

Import sqalx

import "github.com/heetch/sqalx"

Usage

package main

import (
	"log"

	"github.com/heetch/sqalx"
	"github.com/jmoiron/sqlx"
	_ "github.com/lib/pq"
)

func main() {
	// Connect to PostgreSQL with sqlx.
	db, err := sqlx.Connect("postgres", "user=foo dbname=bar sslmode=disable")
	if err != nil {
		log.Fatal(err)
	}

	defer db.Close()

	// Pass the db to sqalx.
	// It returns a sqalx.Node. A Node is a wrapper around sqlx.DB or sqlx.Tx.
	node, err := sqalx.New(db)
	if err != nil {
		log.Fatal(err)
	}

	err = createUser(node)
	if err != nil {
		log.Fatal(err)
	}
}

func createUser(node sqalx.Node) error {
	// Exec a query
	_, _ = node.Exec("INSERT INTO ....") // you can use a node as if it were a *sqlx.DB or a *sqlx.Tx

	// Let's create a transaction.
	// A transaction is also a sqalx.Node.
	tx, err := node.Beginx()
	if err != nil {
		return err
	}
	defer tx.Rollback()

	_, _ = tx.Exec("UPDATE ...")

	// Now we call another function and pass it the transaction.
	err = updateGroups(tx)
	if err != nil {
		return nil
	}

	return tx.Commit()
}

func updateGroups(node sqalx.Node) error {
	// Notice we are creating a new transaction.
	// This would normally cause a dead lock without sqalx.
	tx, err := node.Beginx()
	if err != nil {
		return err
	}
	defer tx.Rollback()

	_, _ = tx.Exec("INSERT ...")
	_, _ = tx.Exec("UPDATE ...")
	_, _ = tx.Exec("DELETE ...")

	return tx.Commit()
}

PostgreSQL Savepoints

When using the PostgreSQL driver, an option can be passed to New to enable the use of PostgreSQL Savepoints for nested transactions.

node, err := sqalx.New(db, sqalx.SavePoint(true))

Issue

Please open an issue if you encounter any problem.

License

The library is released under the MIT license. See LICENSE file.

Documentation

Index

• Variables
• type Driver
• type Node
  • func Connect(driverName, dataSourceName string, options ...Option) (Node, error)
  • func New(db *sqlx.DB, options ...Option) (Node, error)
  • func NewFromTransaction(tx *sqlx.Tx, options ...Option) (Node, error)
• type Option
  • func SavePoint(enabled bool) Option

Variables

var (
	// ErrNotInTransaction is returned when using Commit
	// outside of a transaction.
	ErrNotInTransaction = errors.New("not in transaction")

	// ErrIncompatibleOption is returned when using an option incompatible
	// with the selected driver.
	ErrIncompatibleOption = errors.New("incompatible option")
)

Types

type Driver

type Driver interface {
	sqlx.Execer
	sqlx.ExecerContext
	sqlx.Queryer
	sqlx.QueryerContext
	QueryRow(string, ...interface{}) *sql.Row
	QueryRowContext(context.Context, string, ...interface{}) *sql.Row
	sqlx.Preparer
	sqlx.PreparerContext
	BindNamed(query string, arg interface{}) (string, []interface{}, error)
	DriverName() string
	Get(dest interface{}, query string, args ...interface{}) error
	MustExec(query string, args ...interface{}) sql.Result
	NamedExec(query string, arg interface{}) (sql.Result, error)
	NamedQuery(query string, arg interface{}) (*sqlx.Rows, error)
	PrepareNamed(query string) (*sqlx.NamedStmt, error)
	Preparex(query string) (*sqlx.Stmt, error)
	Rebind(query string) string
	Select(dest interface{}, query string, args ...interface{}) error
}

A Driver can query the database. It can either be a *sqlx.DB or a *sqlx.Tx and therefore is limited to the methods they have in common.

type Node

type Node interface {
	Driver

	// Close the underlying sqlx connection.
	Close() error
	// Begin a new transaction.
	Beginx() (Node, error)
	// Rollback the associated transaction.
	Rollback() error
	// Commit the assiociated transaction.
	Commit() error
	// Tx returns the underlying transaction.
	Tx() *sqlx.Tx

	// Load returns the value stored in the map for a key, or nil if no
	// value is present.
	// The ok result indicates whether value was found in the map.
	Load(key interface{}) (value interface{}, ok bool)
	// Store sets the value for a key.
	Store(key, value interface{})
	// LoadOrStore returns the existing value for the key if present.
	// Otherwise, it stores and returns the given value.
	// The loaded result is true if the value was loaded, false if stored.
	LoadOrStore(key, value interface{}) (actual interface{}, loaded bool)
	// Delete deletes the value for a key.
	Delete(key interface{})
	// Range calls f sequentially for each key and value present in the map.
	// If f returns false, range stops the iteration.
	//
	// Range does not necessarily correspond to any consistent snapshot of the Map's
	// contents: no key will be visited more than once, but if the value for any key
	// is stored or deleted concurrently, Range may reflect any mapping for that key
	// from any point during the Range call.
	//
	// Range may be O(N) with the number of elements in the map even if f returns
	// false after a constant number of calls.
	Range(f func(key, value interface{}) bool)

	// DeferToCommit defers the execution of the given function until (if) the
	// transaction is committed. Deferred function calls are pushed onto a stack.
	// After the transaction commits, its deferred calls are executed in a
	// different goroutine, in last-in-first-out order.
	DeferToCommit(f func())
	// DeferToRollback defers the execution of the given function until (if) the
	// transaction is aborted. Deferred function calls are pushed onto a stack.
	// After the transaction aborts, its deferred calls are executed in a
	// different goroutine, in last-in-first-out order.
	DeferToRollback(f func())
}

A Node is a database driver that can manage nested transactions.

func Connect

func Connect(driverName, dataSourceName string, options ...Option) (Node, error)

Connect to a database.

func New

func New(db *sqlx.DB, options ...Option) (Node, error)

New creates a new Node with the given DB.

func NewFromTransaction

func NewFromTransaction(tx *sqlx.Tx, options ...Option) (Node, error)

NewFromTransaction creates a new Node from the given transaction.

type Option

type Option func(*node) error

Option to configure sqalx

func SavePoint

func SavePoint(enabled bool) Option

SavePoint option enables PostgreSQL Savepoints for nested transactions.