Documentation ¶
Overview ¶
Package schema offers utilities to create and maintain a database schema.
Index ¶
- Constants
- Variables
- func SchemaTableExists(tx database.Tx) (bool, error)
- type Check
- type Hook
- type Schema
- func (s *Schema) Add(update Update)
- func (s *Schema) Check(check Check)
- func (s *Schema) Dump(src database.DB) (string, error)
- func (s *Schema) Ensure(src database.DB) (int, error)
- func (s *Schema) File(path string)
- func (s *Schema) Fresh(statement string)
- func (s *Schema) Hook(hook Hook)
- func (s *Schema) Len() int
- func (s *Schema) Trim(version int) []Update
- type Update
Constants ¶
const StmtCreateTable = `` /* 172-byte string literal not displayed */
StmtCreateTable represents a query for creating a schema table.
const StmtDump = `
INSERT INTO schema (version, updated_at) VALUES (%d, strftime("%%s"))
`
StmtDump represents a query to insert a query when performing a dump query.
const StmtInsertSchemaVersion = `
INSERT INTO schema (version, updated_at) VALUES (?, strftime("%s"))
`
StmtInsertSchemaVersion represents an insert query for inserting versions into the schema.
const StmtSchemaTableExists = `
SELECT COUNT(name) FROM sqlite_master WHERE type = 'table' AND name = 'schema'
`
StmtSchemaTableExists represents a query for checking if the schema table exists.
const StmtSelectSchemaVersions = `
SELECT version FROM schema ORDER BY version
`
StmtSelectSchemaVersions represents a query to get the version from the schema table
const StmtSelectTableSQL = `
SELECT sql FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name != 'schema' ORDER BY name
`
StmtSelectTableSQL represents a query to get the sql from a table.
Variables ¶
var ErrGracefulAbort = errors.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 ¶
Types ¶
type Check ¶
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 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(fileSystem fsys.FileSystem) *Schema
Empty creates a new schema with no updates.
func New ¶
func New(fileSystem fsys.FileSystem, updates []Update) *Schema
New creates a new schema Schema with the given updates.
func (*Schema) Add ¶
Add a new update to the schema. It will be appended at the end of the existing series.
func (*Schema) 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 ¶
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 ¶
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 'schema' 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) File ¶
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 ¶
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 ¶
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.