Documentation
¶
Overview ¶
Package herd provides support for running migrations against a PostgreSQL database.
Example ¶
package main
import (
"context"
"database/sql"
"embed"
"log/slog"
"github.com/mattdowdell/sandbox/pkg/herd"
)
//go:embed testdata/migrations/*.sql
var migrationFS embed.FS
func main() {
ctx := context.Background()
migrations, _ := herd.CollectFileMigrations(migrationFS)
migrator, _ := herd.New(migrations)
db, _ := sql.Open("example", "dsn")
result, err := migrator.Migrate(ctx, db)
if err != nil {
slog.Error("failed to run migrate", slog.Any("error", err))
return
}
slog.Info("migration completed", slog.Any("result", result))
}
Index ¶
Examples ¶
Constants ¶
const ( TableNameSystem = "herd_system_migrations" TableNameUser = "herd_user_migrations" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DB ¶
type DB interface {
ExecContext(context.Context, string, ...any) (sql.Result, error)
QueryContext(context.Context, string, ...any) (*sql.Rows, error)
QueryRowContext(context.Context, string, ...any) *sql.Row
}
DB contains the methods from sql.DB that migrations can use.
type FileMigration ¶
type FileMigration struct {
// contains filtered or unexported fields
}
FileMigration uses the contents of a SQL file as a migration.
func NewFileMigration ¶
func NewFileMigration(version int64, contents string) *FileMigration
NewFileMigration creates a new FileMigration.
func NewFileMigrationFromFS ¶
func NewFileMigrationFromFS(filesystem fs.FS, path string) (*FileMigration, error)
NewFileMigrationFromFS reads the file at the path from the filesystem. The last element of the path is taken as the filename, and is passed with the contents to NewFileMigrationFromFilename.
func NewFileMigrationFromFilename ¶
func NewFileMigrationFromFilename(filename, contents string) (*FileMigration, error)
NewFileMigrationFromFilename extracts the migration version from the given filename and calls NewFileMigration.
The version must be at the start of the filename followed by a underscore ("_"). For example, 1_initial.sql would have a version of 1. Versions can be padded with 0s to make them easier to view in a file browser. 0001_initial.sql and 1_initial.sql would have the same version.
func (*FileMigration) Migrate ¶
func (m *FileMigration) Migrate(ctx context.Context, db DB) error
Migrate executes the SQL file contents against the database.
func (*FileMigration) Version ¶
func (m *FileMigration) Version() int64
Version returns the migration version.
type Herd ¶ added in v0.2.55
type Herd struct {
// contains filtered or unexported fields
}
Herd is used to migrate a database using a set of migrations.
Migrations are applied in order of version, starting from the lowest to highest. Versions do not need to be consecutive. This allows version numbers to be based on dates.
type Migration ¶
type Migration interface {
// Version returns the migration version. It must be greater than 0 and unique across all
// migrations.
Version() int64
// Migrate applies the schema or data changes for the migration.
Migrate(context.Context, DB) error
}
Migration implementations apply schema or data changes to a database.
type Option ¶ added in v0.2.55
type Option interface {
// contains filtered or unexported methods
}
Option adjust the behaviour of Herd.
func WithBuildInfo ¶ added in v0.2.55
WithBuildInfo overrides the soure of the code version and revision used in migration records. Defaults to the output of runtime/debug.ReadBuildInfo.
type Result ¶ added in v0.2.51
type Result struct {
// Before is the migration version before applying any migrations. A value of 0 indicates that
// no migrations had been applied previously.
Before int64
// After is the migration version after applying any migrations. After will equal Before when no
// pending migrations were found.
After int64
}
Result contains the migration version before and after the pending migrations were applied.
Source Files
Directories