1package database
 2
 3import (
 4	"context"
 5	"errors"
 6	"time"
 7)
 8
 9var (
10	// ErrVersionNotFound must be returned by [GetMigration] or [GetLatestVersion] when a migration
11	// does not exist.
12	ErrVersionNotFound = errors.New("version not found")
13
14	// ErrNotImplemented must be returned by methods that are not implemented.
15	ErrNotImplemented = errors.New("not implemented")
16)
17
18// Store is an interface that defines methods for tracking and managing migrations. It is used by
19// the goose package to interact with a database. By defining a Store interface, multiple
20// implementations can be created to support different databases without reimplementing the
21// migration logic.
22//
23// This package provides several dialects that implement the Store interface. While most users won't
24// need to create their own Store, if you need to support a database that isn't currently supported,
25// you can implement your own!
26type Store interface {
27	// Tablename is the name of the version table. This table is used to record applied migrations
28	// and must not be an empty string.
29	Tablename() string
30	// CreateVersionTable creates the version table, which is used to track migrations.
31	CreateVersionTable(ctx context.Context, db DBTxConn) error
32	// Insert a version id into the version table.
33	Insert(ctx context.Context, db DBTxConn, req InsertRequest) error
34	// Delete a version id from the version table.
35	Delete(ctx context.Context, db DBTxConn, version int64) error
36	// GetMigration retrieves a single migration by version id. If the query succeeds, but the
37	// version is not found, this method must return [ErrVersionNotFound].
38	GetMigration(ctx context.Context, db DBTxConn, version int64) (*GetMigrationResult, error)
39	// GetLatestVersion retrieves the last applied migration version. If no migrations exist, this
40	// method must return [ErrVersionNotFound].
41	GetLatestVersion(ctx context.Context, db DBTxConn) (int64, error)
42	// ListMigrations retrieves all migrations sorted in descending order by id or timestamp. If
43	// there are no migrations, return empty slice with no error. Typically this method will return
44	// at least one migration, because the initial version (0) is always inserted into the version
45	// table when it is created.
46	ListMigrations(ctx context.Context, db DBTxConn) ([]*ListMigrationsResult, error)
47}
48
49type InsertRequest struct {
50	Version int64
51
52	// TODO(mf): in the future, we maybe want to expand this struct so implementors can store
53	// additional information. See the following issues for more information:
54	//  - https://github.com/pressly/goose/issues/422
55	//  - https://github.com/pressly/goose/issues/288
56}
57
58type GetMigrationResult struct {
59	Timestamp time.Time
60	IsApplied bool
61}
62
63type ListMigrationsResult struct {
64	Version   int64
65	IsApplied bool
66}