database

Documentation

Overview

Package database defines a generic Store interface for goose to use when interacting with the database. It is meant to be generic and not tied to any specific database technology.

At a high level, a Store is responsible for:

• Creating a version table
• Inserting and deleting a version
• Getting a specific version
• Listing all applied versions

Use the NewStore function to create a Store for one of the supported dialects.

For more advanced use cases, it's possible to implement a custom Store for a database that goose does not support.

Index

• Variables
• type DBTxConn
• type Dialect
• type GetMigrationResult
• type InsertRequest
• type ListMigrationsResult
• type Store
  • func NewStore(dialect Dialect, tablename string) (Store, error)
• type StoreExtender

Variables

var (
	// ErrVersionNotFound must be returned by [GetMigration] or [GetLatestVersion] when a migration
	// does not exist.
	ErrVersionNotFound = errors.New("version not found")

	// ErrNotImplemented must be returned by methods that are not implemented.
	ErrNotImplemented = errors.New("not implemented")
)

Types

type DBTxConn

type DBTxConn interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}

DBTxConn is a thin interface for common methods that is satisfied by *sql.DB, *sql.Tx and *sql.Conn.

There is a long outstanding issue to formalize a std lib interface, but alas. See: https://github.com/golang/go/issues/14468

type Dialect

type Dialect string

Dialect is the type of database dialect.

const (
	DialectClickHouse Dialect = "clickhouse"
	DialectMSSQL      Dialect = "mssql"
	DialectMySQL      Dialect = "mysql"
	DialectPostgres   Dialect = "postgres"
	DialectRedshift   Dialect = "redshift"
	DialectSQLite3    Dialect = "sqlite3"
	DialectTiDB       Dialect = "tidb"
	DialectTurso      Dialect = "turso"
	DialectVertica    Dialect = "vertica"
	DialectYdB        Dialect = "ydb"
	DialectStarrocks  Dialect = "starrocks"
)

type GetMigrationResult

type GetMigrationResult struct {
	Timestamp time.Time
	IsApplied bool
}

type InsertRequest

type InsertRequest struct {
	Version int64
}

type ListMigrationsResult

type ListMigrationsResult struct {
	Version   int64
	IsApplied bool
}

type Store

type Store interface {
	// Tablename is the name of the version table. This table is used to record applied migrations
	// and must not be an empty string.
	Tablename() string
	// CreateVersionTable creates the version table, which is used to track migrations.
	CreateVersionTable(ctx context.Context, db DBTxConn) error
	// Insert a version id into the version table.
	Insert(ctx context.Context, db DBTxConn, req InsertRequest) error
	// Delete a version id from the version table.
	Delete(ctx context.Context, db DBTxConn, version int64) error
	// GetMigration retrieves a single migration by version id. If the query succeeds, but the
	// version is not found, this method must return [ErrVersionNotFound].
	GetMigration(ctx context.Context, db DBTxConn, version int64) (*GetMigrationResult, error)
	// GetLatestVersion retrieves the last applied migration version. If no migrations exist, this
	// method must return [ErrVersionNotFound].
	GetLatestVersion(ctx context.Context, db DBTxConn) (int64, error)
	// ListMigrations retrieves all migrations sorted in descending order by id or timestamp. If
	// there are no migrations, return empty slice with no error. Typically this method will return
	// at least one migration, because the initial version (0) is always inserted into the version
	// table when it is created.
	ListMigrations(ctx context.Context, db DBTxConn) ([]*ListMigrationsResult, error)
}

Store is an interface that defines methods for tracking and managing migrations. It is used by the goose package to interact with a database. By defining a Store interface, multiple implementations can be created to support different databases without reimplementing the migration logic.

This package provides several dialects that implement the Store interface. While most users won't need to create their own Store, if you need to support a database that isn't currently supported, you can implement your own!

func NewStore

func NewStore(dialect Dialect, tablename string) (Store, error)

NewStore returns a new Store implementation for the given dialect.

type StoreExtender

type StoreExtender interface {
	Store

	// TableExists checks if the migrations table exists in the database. Implementing this method
	// allows goose to optimize table existence checks by using database-specific system catalogs
	// (e.g., pg_tables for PostgreSQL, sqlite_master for SQLite) instead of generic SQL queries.
	//
	// Return [errors.ErrUnsupported] if the database does not provide an efficient way to check
	// table existence.
	TableExists(ctx context.Context, db DBTxConn) (bool, error)
}

StoreExtender is an extension of the Store interface that provides optional optimizations and database-specific features. While not required by the core goose package, implementing these methods can improve performance and functionality for specific databases.

IMPORTANT: This interface may be expanded in future versions. Implementors MUST be prepared to update their implementations when new methods are added, either by implementing the new functionality or returning errors.ErrUnsupported.

The goose package handles these extended capabilities through a [controller.StoreController], which automatically uses optimized methods when available while falling back to default behavior when they're not implemented.

Example usage to verify implementation:

var _ StoreExtender = (*CustomStoreExtended)(nil)

In short, it's exported to allows implementors to have a compile-time check that they are implementing the interface correctly.