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 Backup() backups.Backup
• 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)
• type ResetToken
  • func NewResetToken(id ulid.ULID) (token *ResetToken, err error)
  • func (t *ResetToken) Sign() (_ string, secret []byte, err error)
  • func (t *ResetToken) Verify(signature string, secret []byte) (err error)
• type SigningInfo
  • func NewSigningInfo(expires time.Duration) (info SigningInfo, err error)
  • func (d SigningInfo) IsExpired() bool
• type VerificationToken
  • func NewVerificationToken(email string) (token *VerificationToken, err error)
  • func (t *VerificationToken) Sign() (_ string, secret []byte, err error)
  • func (t *VerificationToken) Verify(signature string, secret []byte) (err error)

Variables

var (
	ErrNotConnected   = errors.New("not connected to the database")
	ErrReadOnly       = errors.New("connected in read-only 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")
)

var (
	ErrMissingEmail       = errors.New("email address is required")
	ErrMissingUserID      = errors.New("user id is required")
	ErrTokenMissingEmail  = errors.New("email verification token is missing email address")
	ErrTokenMissingUserID = errors.New("email verification token is missing user id")
	ErrTokenExpired       = errors.New("email verification token has expired")
	ErrInvalidSecret      = errors.New("invalid secret for email token verification")
	ErrTokenInvalid       = errors.New("email verification token has invalid signature")
	ErrSQLite3Conn        = errors.New("could not get sqlite3 connection for backups")
)

Functions

func Backup

func Backup() backups.Backup

Backup returns the underlying sqlite3 backup manager.

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.

type ResetToken

type ResetToken struct {
	UserID ulid.ULID `msgpack:"user_id"`
	SigningInfo
}

ResetToken packages a user ID with random data and an expiration time so that it can be serialized and hashed into a token which can be sent to users.

func NewResetToken

func NewResetToken(id ulid.ULID) (token *ResetToken, err error)

NewResetToken creates a token struct from a user ID that expires in 15 minutes.

func (*ResetToken) Sign

func (t *ResetToken) Sign() (_ string, secret []byte, err error)

Sign creates a base64 encoded string from the token data so that it can be sent to users as part of a URL. The returned secret should be stored in the database so that the string can be recomputed when verifying a user provided token.

func (*ResetToken) Verify

func (t *ResetToken) Verify(signature string, secret []byte) (err error)

Verify checks that a token was signed with the secret and is not expired.

type SigningInfo

type SigningInfo struct {
	ExpiresAt time.Time `msgpack:"expires_at"`
	Nonce     []byte    `msgpack:"nonce"`
}

SigningInfo contains an expiration time and a nonce that is used to sign the token.

func NewSigningInfo

func NewSigningInfo(expires time.Duration) (info SigningInfo, err error)

Create new signing info with a time expiration.

func (SigningInfo) IsExpired

func (d SigningInfo) IsExpired() bool

type VerificationToken

type VerificationToken struct {
	Email string `msgpack:"email"`
	SigningInfo
}

VerificationToken packages an email address with random data and an expiration time so that it can be serialized and hashed into a token which can be sent to users.

func NewVerificationToken

func NewVerificationToken(email string) (token *VerificationToken, err error)

NewVerificationToken creates a token struct from an email address that expires in 7 days.

func (*VerificationToken) Sign

func (t *VerificationToken) Sign() (_ string, secret []byte, err error)

Sign creates a base64 encoded string from the token data so that it can be sent to users as part of a URL. The returned secret should be stored in the database so that the string can be recomputed when verifying a user provided token.

func (*VerificationToken) Verify

func (t *VerificationToken) Verify(signature string, secret []byte) (err error)

Verify checks that a token was signed with the secret and is not expired.