txmanager

README

txmanager

The txnmanager package is a nested transation manager for database/sql.

SYNOPSIS

Use TxBegin to start a transaction, and TxCommit or TxRollback to finish the transaction.

import (
	"database/sql"

	"github.com/shogo82148/txmanager"
)

func Example(db *sql.DB) {
	dbm := txmanager.NewDB(db)

	// start a transaction
	tx, _ := dbm.TxBegin()
	defer tx.TxFinish()

	// Exec INSERT in a transaction
	_, err := tx.Exec("INSERT INTO t1 (id) VALUES(1)")
	if err != nil {
		tx.TxRollback()
	}
	tx.TxCommit()
}

You can manage txmanager.DB with txmanager.Do.

import (
	"database/sql"

	"github.com/shogo82148/txmanager"
)

func Example(db *sql.DB) {
	dbm := txmanager.NewDB(db)
	txmanager.Do(dbm, func(tx txmanager.Tx) error {
		// Exec INSERT in a transaction
		_, err := tx.Exec("INSERT INTO t1 (id) VALUES(1)")
		return err
	})
}

NESTED TRANSACTION

import (
	"database/sql"

	"github.com/shogo82148/txmanager"
)

func Foo(dbm *txmanager.DB) error {
	return txmanager.Do(dbm, func(tx txmanager.Tx) error {
		_, err := tx.Exec("INSERT INTO t1 (id) VALUES(1)")
		return err
	})
}

func Example(db *sql.DB) {
	dbm := txmanager.NewDB(db)

	Foo(dbm)

	txmanager.Do(dbm, func(tx txmanager.Tx) error {
		return Foo(tx)
	})
}

END HOOK

TxCommit necessarily does not do COMMIT SQL statemant. So following code sometimes outputs wrong log.

func Foo(dbm *txmanager.DB) error {
	err := txmanager.Do(dbm, func(tx txmanager.Tx) error {
		_, err := tx.Exec("INSERT INTO t1 (id) VALUES(1)"); err != nil {
		return err
	})
	if err != nil {
		return err
	}

	// TxCommit is success, while the transaction might fail
	log.Println("COMMIT is success!!!")
	return nil
}

Use TxAddEndHook to avoid it. It is inspired by DBIx::TransactionManager::EndHook.

func Foo(dbm *txmanager.DB) error {
	return txmanager.Do(dbm, func(tx txmanager.Tx) error {
		if _, err := tx.Exec("INSERT INTO t1 (id) VALUES(1)"); err != nil {
			return err
		}
		tx.TxAddEndHook(func() error {
			// It is called if all transactions are executed successfully.
			log.Println("COMMIT is success!!!")
		})
		return nil
	})
}

LICENSE

This software is released under the MIT License, see LICENSE.txt.

godoc

See godoc for more imformation.

Documentation

Overview

The txnmanager is a nested transation manager for database/sql. This software is released under the MIT License, see https://github.com/shogo82148/txmanager/blob/master/LICENSE.txt .

Index

• Variables
• func Do(d DB, f func(t Tx) error) error
• type Beginner
• type Committer
• type DB
  • func NewDB(d *sql.DB) DB
• type EndHookAdder
• type Executor
• type Tx

Variables

var ErrChildrenNotDone = errors.New("txmanager: children transactions are not done")

Functions

func Do

func Do(d DB, f func(t Tx) error) error

Do executes the function in a transaction.

Types

type Beginner

type Beginner interface {
	// TxBegin starts a transaction.
	// If the DB is not a transaction, TxBegin does BEGIN at here.
	// Otherwise, its behavior is implementation-dependent.
	TxBegin() (Tx, error)
}

a Beginner starts a transaction.

type Committer

type Committer interface {
	// TxCommit commits the transaction.
	// If the DB is in a root transaction, TxCommit does COMMIT at here.
	// Otherwise, its behavior is implementation-dependent.
	TxCommit() error

	// TxRollback aborts the transaction.
	// If the DB is in a root transaction, TxRollback does ROLLBACK at here.
	// Otherwise, its behavior is implementation-dependent.
	TxRollback() error

	// TxFinish aborts the transaction if it is not commited.
	TxFinish() error
}

a Committer finishes a transaction

type DB

type DB interface {
	Executor
	Beginner
}

func NewDB

func NewDB(d *sql.DB) DB

NewDB creates a basic transaction manager. TxBegin/TxCommit doesn't do BEGIN/COMMIT in a transaction. They just push/pop transaction stack and do nothing. TxRollback always does ROLLBACK and finish all related transactions includes parents.

type EndHookAdder

type EndHookAdder interface {
	// TxAddEndHook add a hook function to txmanager.
	// Hooks are executed only all transactions are executed successfully.
	// If some transactions are failed, they aren't executed.
	TxAddEndHook(hook func() error) error
}

an EndHookAdder adds end hooks

type Executor

type Executor interface {
	// Exec executes a query without returning any rows.
	// See sql.DB and sql.Tx for more information.
	Exec(query string, args ...interface{}) (sql.Result, error)

	// Prepare creates a prepared statement for later queries or executions.
	// See sql.DB and sql.Tx for more information.
	Prepare(query string) (*sql.Stmt, error)

	// Query executes a query that returns rows, typically a SELECT.
	// See sql.DB and sql.Tx for more information.
	Query(query string, args ...interface{}) (*sql.Rows, error)

	// QueryRow executes a query that is expected to return at most one row.
	// See sql.DB and sql.Tx for more information.
	QueryRow(query string, args ...interface{}) *sql.Row
}

an Executor executes SQL query.

type Tx

type Tx interface {
	Executor
	Beginner
	Committer
	EndHookAdder
}