pgtxdb

README

pgtxdb

Description

Single transaction sql driver for Golang x PostgreSQL. This is almost clone of go-txdb with a bit of PostgreSQL tweeks.

• When conn.Begin() is called, this library executes SAVEPOINT pgtxdb_xxx; instead of actually begins transaction.
• tx.Commit() does nothing.
• ROLLBACK TO SAVEPOINT pgtxdb_xxx; will be executed upon tx.Rollback() call so that it can emulate transaction rollback.
• Above features enable us to emulate multiple transactions in one test case.

Run test

Make sure PostgreSQL is running.

create database pgtxdbtest;
create user pgtxdbtest;

If you have Docker installed on your machine, run make test.

Documentation

Overview

Package pgtxdb is a single transaction based database sql driver for PostgreSQL. When the connection is opened, it starts a transaction and all operations performed on this *sql.DB will be within that transaction. If concurrent actions are performed, the lock is acquired and connection is always released the statements and rows are not holding the connection.

Why is it useful. A very basic use case would be if you want to make functional tests you can prepare a test database and within each test you do not have to reload a database. All tests are isolated within transaction and though, performs fast. And you do not have to interface your sql.DB reference in your code, txdb is like a standard sql.Driver.

This driver supports any sql.Driver connection to be opened. You can register txdb for different sql drivers and have it under different driver names. Under the hood whenever a txdb driver is opened, it attempts to open a real connection and starts transaction. When close is called, it rollbacks transaction leaving your prepared test database in the same state as before.

Given, you have a mysql database called txdb_test and a table users with a username column.

Example:

		package main

		import (
			"database/sql"
			"log"

			"github.com/DATA-DOG/go-txdb"
			_ "github.com/go-sql-driver/mysql"
		)

		func init() {
			// we register an sql driver named "txdb"
			txdb.Register("txdb", "mysql", "root@/txdb_test")
		}

		func main() {
      // dsn serves as an unique identifier for connection pool
			db, err := sql.Open("txdb", "identifier")
			if err != nil {
				log.Fatal(err)
			}
			defer db.Close()

			if _, err := db.Exec(`INSERT INTO users(username) VALUES("gopher")`); err != nil {
				log.Fatal(err)
			}
		}

Every time you will run this application, it will remain in the same state as before.

Index

• func Register(name, drv, dsn string)

Functions

func Register

func Register(name, drv, dsn string)

Register a txdb sql driver under the given sql driver name which can be used to open a single transaction based database connection.

When Open is called any number of times it returns the same transaction connection. Any Begin, Commit calls will not start or close the transaction.

When Close is called, the transaction is rolled back.

Use drv (Driver) and dsn (DataSourceName) as the standard sql properties for your test database connection to be isolated within transaction.

The drv and dsn are the same items passed into `sql.Open(drv, dsn)`.

Note: if you open a secondary database, make sure to differianciate the dsn string when opening the sql.DB. The transaction will be isolated within that dsn