gotabase

README

gotabase

A simple database connection and migration handler for go applications. It has 2 primary applications:

1. serving as a go-between (pun not intended) between database/sql and your program by providing an abstraction layer, thus somewhat decoupling from a single database handling library,
2. making connection handling easier by providing migration functionality and hiding connection management with easy access methods.

Usage

Connection handling

At the start of your program, run

err := gotabase.InitialiseConnection(connectionString, driverName)

to prepare the database connection.

After that, you can access the connection pool by using the gotabase.GetConnection() method.

Migrations

You can execute migrations by calling the Migrate method in the migrations package.

There are a couple of important things to remember:

1. You should store your migrations in a file with .sql extension. These files should be contained in a folder called sql. The files should have names consisting of a single number, starting at 0 and going SEQUENTIALLY up (as in 0.sql, 1.sql, 2.sql...). If you need to remove a migration after a next number has been used, leave the file empty instead of removing it.
2. Your database model must, from the very beginning, include a migrations table (it MUST be created in your 0.sql migration file). By default, it should contain a single integer column called id as a primary key. Note that this behaviour can be modified or adjusted to a different DBMS by overwriting the MigrationCreator, IsInitialMigrationError and LatestMigrationSelectorSql variables of the migrations package.
3. The interface for providing database migrations files must be implemented, as there's no default implementation. You can, however, use the embed.FS struct, as it fulfills the conditions of this interface. See below for more details.

Usage of embed.FS as migration provider

The easiest way to provide migration files is to use the embed.FS struct. First, create sql folder somewhere within your project directory structure. Then, in the same directory as the sql folder, declare variable in the following way:

var (
	//go:embed sql
	migrations embed.FS
)

This will embed the contents of the sql directory in your output binary file, making it easy to distribute those files. You can also use the migrations variable in place of the provider interface.

Documentation

Index

• func CloseConnection() error
• func InitialiseConnection(connectionString string, driver string) error
• type Connector
  • func GetConnection() Connector
• type Result
• type Row
• type Rows
• type Transaction
  • func BeginTransaction() (*Transaction, error)
  • func (t *Transaction) Commit() error
  • func (t *Transaction) Exec(sql string, args ...interface{}) (Result, error)
  • func (t *Transaction) QueryRow(sql string, args ...interface{}) (Row, error)
  • func (t *Transaction) QueryRows(sql string, args ...interface{}) (Rows, error)
  • func (t *Transaction) Rollback() error

Functions

func CloseConnection

func CloseConnection() error

func InitialiseConnection

func InitialiseConnection(connectionString string, driver string) error

Types

type Connector

type Connector interface {
	QueryRow(sql string, args ...interface{}) (Row, error)
	QueryRows(sql string, args ...interface{}) (Rows, error)
	Exec(sql string, args ...interface{}) (Result, error)
}

Connector provides an interface for database operations that can be performed during application operation. Returned types such as Row, Rows, and Result provide an abstraction layer over database/sql types, but are compatible with them.

func GetConnection

func GetConnection() Connector

type Result

type Result interface {
	LastInsertId() (int64, error)
	RowsAffected() (int64, error)
}

type Row

type Row interface {
	Scan(dest ...any) error
}

type Rows

type Rows interface {
	Close() error
	Scan(dest ...any) error
	Next() bool
}

type Transaction

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

func BeginTransaction

func BeginTransaction() (*Transaction, error)

func (*Transaction) Commit

func (t *Transaction) Commit() error

func (*Transaction) Exec

func (t *Transaction) Exec(sql string, args ...interface{}) (Result, error)

func (*Transaction) QueryRow

func (t *Transaction) QueryRow(sql string, args ...interface{}) (Row, error)

func (*Transaction) QueryRows

func (t *Transaction) QueryRows(sql string, args ...interface{}) (Rows, error)

func (*Transaction) Rollback

func (t *Transaction) Rollback() error