db

Documentation

Overview

Package db establishes a connection with a Raft replicated sqlite3 database. External packages can use this module to ensure that the database is at the most current schema and can make thread-safe transactions against the database.

Users of the package have to call db.Connect() at least once to use the database, but multiple calls to db.Connect() will not cause an error. A call to db.Close() will require reconnecting before any additional queries are made. Arbitrary transactions to the database can be executed by using db.BeginTx - the module guards a single connection to the database from multiple go routines opening and closing access to the database.

Index

• Variables
• func BeginTx(ctx context.Context, opts *sql.TxOptions) (tx *sql.Tx, err error)
• func Close() (err error)
• func Connect(dsn string, readonly bool) (err error)
• func InitializeSchema(empty bool) (err error)
• type DSN
  • func ParseDSN(uri string) (_ *DSN, err error)
• type Migration
  • func Migrations() (data []*Migration, err error)
  • func (m *Migration) SQL() (_ string, err error)

Variables

var (
	ErrNotconnected   = errors.New("not connected to the database")
	ErrReadOnly       = errors.New("connected in readonly mode")
	ErrNotFound       = errors.New("record not found or no rows returned")
	ErrCannotParseDSN = errors.New("could not parse dsn, specify scheme:///path/to/data.db")
	ErrUnknownScheme  = errors.New("must specify a sqlite3 DSN")
)

Functions

func BeginTx

func BeginTx(ctx context.Context, opts *sql.TxOptions) (tx *sql.Tx, err error)

BeginTx creates a transaction with the connected database but returns an error if the database is not connected. If the database is set to readonly mode and the transaction options are not readonly, an error is returned.

func Close

func Close() (err error)

Close the database safely and allow for reconnect after close by resetting the package variables. No errors occur if the database is not connected.

func Connect

func Connect(dsn string, readonly bool) (err error)

Connect to the sqlite3 database specified by the DSN. Connecting in readonly mode is managed by the package, not the database and is enforced by package functions. Subsequent calls to Connect will be ignored even if a different DSN or readonly mode is passed to the function.

func InitializeSchema

func InitializeSchema(empty bool) (err error)

Initialize schema applies any unapplied migrations to the database and should be run when the database is first connected to. If empty is true then the migration table is created and all migrations are applied. If it is not true then the current migration of the database is fetched and all unapplied migrations are applied.

Types

type DSN

type DSN struct {
	Scheme string
	Path   string
}

DSN represents the parsed components of an embedded database service.

func ParseDSN

func ParseDSN(uri string) (_ *DSN, err error)

DSN parsing and handling

type Migration

type Migration struct {
	ID      int       // The unique sequence ID of the migration
	Name    string    // The human readable name of the migration
	Version string    // The package version when the migration was applied
	Created time.Time // The timestamp when the migration was applied
	Path    string    // The path of the migration in the filesystem
}

Migration is used to represent both a SQL migration from the embedded file system and a migration record in the database. These records are compared to ensure the database is as up to date as possible before the application starts.

func Migrations

func Migrations() (data []*Migration, err error)

Migrations returns the migration files from the embedded file system.

func (*Migration) SQL

func (m *Migration) SQL() (_ string, err error)

SQL loads the schema sql query from the embedded file on disk.