schema

Documentation

Overview

Package schema offers utilities to create and maintain a database schema.

Index

• Variables
• func DoesSchemaTableExist(ctx context.Context, tx *sql.Tx) (bool, error)
• func DotGo(updates map[int]Update, name string) error
• type Check
• type Hook
• type Schema
  • func Empty() *Schema
  • func New(updates []Update) *Schema
  • func NewFromMap(versionsToUpdates map[int]Update) *Schema
  • func (s *Schema) Add(update Update)
  • func (s *Schema) Check(check Check)
  • func (s *Schema) Dump(db *sql.DB) (string, error)
  • func (s *Schema) Ensure(db *sql.DB) (int, error)
  • func (s *Schema) ExerciseUpdate(version int, hook func(*sql.DB)) (*sql.DB, error)
  • func (s *Schema) File(path string)
  • func (s *Schema) Fresh(statement string)
  • func (s *Schema) Hook(hook Hook)
  • func (s *Schema) Trim(version int) []Update
• type Update

Variables

var ErrGracefulAbort = fmt.Errorf("schema check gracefully aborted")

ErrGracefulAbort is a special error that can be returned by a Check function to force Schema.Ensure to abort gracefully.

Every change performed so by the Check will be committed, although ErrGracefulAbort will be returned.

Functions

func DoesSchemaTableExist

func DoesSchemaTableExist(ctx context.Context, tx *sql.Tx) (bool, error)

DoesSchemaTableExist return whether the schema table is present in the database.

func DotGo

func DotGo(updates map[int]Update, name string) error

DotGo writes '<name>.go' source file in the package of the calling function, containing SQL statements that match the given schema updates.

The <name>.go file contains a "flattened" render of all given updates and can be used to initialize brand new databases using Schema.Fresh().

Types

type Check

type Check func(context.Context, int, *sql.Tx) error

Check is a callback that gets fired all the times Schema.Ensure is invoked, before applying any update. It gets passed the version that the schema is currently at and a handle to the transaction. If it returns nil, the update proceeds normally, otherwise it's aborted. If ErrGracefulAbort is returned, the transaction will still be committed, giving chance to this function to perform state changes.

type Hook

type Hook func(context.Context, int, *sql.Tx) error

Hook is a callback that gets fired when a update gets applied.

type Schema

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

Schema captures the schema of a database in terms of a series of ordered updates.

func Empty

func Empty() *Schema

Empty creates a new schema with no updates.

func New

func New(updates []Update) *Schema

New creates a new schema Schema with the given updates.

func NewFromMap

func NewFromMap(versionsToUpdates map[int]Update) *Schema

NewFromMap creates a new schema Schema with the updates specified in the given map. The keys of the map are schema versions that when upgraded will trigger the associated Update value. It's required that the minimum key in the map is 1, and if key N is present then N-1 is present too, with N>1 (i.e. there are no missing versions).

NOTE: the regular New() constructor would be formally enough, but for extra clarity we also support a map that indicates the version explicitly, see also PR #3704.

func (*Schema) Add

func (s *Schema) Add(update Update)

Add a new update to the schema. It will be appended at the end of the existing series.

func (*Schema) Check

func (s *Schema) Check(check Check)

Check instructs the schema to invoke the given function whenever Ensure is invoked, before applying any due update. It can be used for aborting the operation.

func (*Schema) Dump

func (s *Schema) Dump(db *sql.DB) (string, error)

Dump returns a text of SQL commands that can be used to create this schema from scratch in one go, without going thorugh individual patches (essentially flattening them).

It requires that all patches in this schema have been applied, otherwise an error will be returned.

func (*Schema) Ensure

func (s *Schema) Ensure(db *sql.DB) (int, error)

Ensure makes sure that the actual schema in the given database matches the one defined by our updates.

All updates are applied transactionally. In case any error occurs the transaction will be rolled back and the database will remain unchanged.

A update will be applied only if it hasn't been before (currently applied updates are tracked in the a 'shema' table, which gets automatically created).

If no error occurs, the integer returned by this method is the initial version that the schema has been upgraded from.

func (*Schema) ExerciseUpdate

func (s *Schema) ExerciseUpdate(version int, hook func(*sql.DB)) (*sql.DB, error)

ExerciseUpdate is a convenience for exercising a particular update of a schema.

It first creates an in-memory SQLite database, then it applies all updates up to the one with given version (excluded) and optionally executes the given hook for populating the database with test data. Finally it applies the update with the given version, returning the database handle for further inspection of the resulting state.

func (*Schema) File

func (s *Schema) File(path string)

File extra queries from a file. If the file is exists, all SQL queries in it will be executed transactionally at the very start of Ensure(), before anything else is done.

If a schema hook was set with Hook(), it will be run before running the queries in the file and it will be passed a patch version equals to -1.

func (*Schema) Fresh

func (s *Schema) Fresh(statement string)

Fresh sets a statement that will be used to create the schema from scratch when bootstraping an empty database. It should be a "flattening" of the available updates, generated using the Dump() method. If not given, all patches will be applied in order.

func (*Schema) Hook

func (s *Schema) Hook(hook Hook)

Hook instructs the schema to invoke the given function whenever a update is about to be applied. The function gets passed the update version number and the running transaction, and if it returns an error it will cause the schema transaction to be rolled back. Any previously installed hook will be replaced.

func (*Schema) Trim

func (s *Schema) Trim(version int) []Update

Trim the schema updates to the given version (included). Updates with higher versions will be discarded. Any fresh schema dump previously set will be unset, since it's assumed to no longer be applicable. Return all updates that have been trimmed.

type Update

type Update func(context.Context, *sql.Tx) error

Update applies a specific schema change to a database, and returns an error if anything goes wrong.