common

README

common

common contains helpers for use in different implementations of the Migrator interface.

Hashing

// HashFiles will return as unique hash based on the contents of the specified
// files. If `base` is nil, it will read the paths from the real file system.
//
// Examples:
//
//   HashFiles(nil, "0001_initial.sql")
//   HashFiles(nil, "0001_initial.sql", "0002_users.up.sql")
//   HashDirs(embeddedFS, "migrations/0001_initial.sql")
func HashFiles(base fs.FS, paths ...string) (string, error)

// HashDirs will return as unique hash based on the contents of all files that
// match a given pattern, from any of the given directories. If `base` is nil,
// it will read the directories and files from the real file system.
//
// Examples:
//
//   HashDirs(nil, "*.sql", "migrations")
//   HashDirs(nil, "*.sql", "migrations/old", "migrations/current")
//   HashDirs(embeddedFS, "*.sql", ".")
func HashDirs(base fs.FS, pattern string, dirs ...string) (string, error)

// Returns a unique hash based on the contents of any "*.sql" files found in the
// specified directory.
func HashDir(pathToDir string) (string, error)

// Returns a unique hash based on the contents of the specified file.
func HashFile(pathToFile string) (string, error)

// NewRecursiveHash creates a new [RecursiveHash], and adds any of the given fields
// to it.
//
// Examples:
//
//  hash, _ := NewRecursiveHash()
//  _ = hash.AddField(Field("CreateMigrationsTable", settings.CreateMigrationsTable))
//  _ = hash.AddField(Field("MigrationsTableName", settings.MigrationsTableName))
//  _ = hash.Add([]byte("hello"))
//  _ = hash.Add([]byte("world"))
//  out, _ := hash.String()
func NewRecursiveHash(fields ...HashField) (RecursiveHash, error)

Shelling out

// Execute shells out to a `program`, passing it STDIN (if given) and any specified arguments.
//
// Examples:
//
//   Execute(ctx, nil, "echo", "hello", "world"
//   Execute(ctx, nil, "bash", "-c", "echo 'hello world'"
func Execute(ctx context.Context, stdin io.Reader, program string, args ...string) (string, error)

Documentation

Index

• func Execute(ctx context.Context, stdin io.Reader, program string, args ...string) (string, error)
• func HashDir(pathToDir string) (string, error)
• func HashDirs(base fs.FS, pattern string, dirs ...string) (string, error)
• func HashFile(pathToFile string) (string, error)
• func HashFiles(base fs.FS, paths ...string) (string, error)
• type HashField
  • func Field(key string, value any) HashField
• type RecursiveHash
  • func NewRecursiveHash(fields ...HashField) RecursiveHash
  • func (h RecursiveHash) Add(bytes []byte)
  • func (h RecursiveHash) AddDirs(base fs.FS, pattern string, dirs ...string) error
  • func (h RecursiveHash) AddField(key string, value any)
  • func (h RecursiveHash) AddFields(fields ...HashField)
  • func (h RecursiveHash) AddFiles(base fs.FS, paths ...string) error
  • func (h RecursiveHash) String() string

Functions

func Execute

func Execute(ctx context.Context, stdin io.Reader, program string, args ...string) (string, error)

Execute shells out to a `program`, passing it STDIN (if given) and any specified arguments.

Examples:

Execute(ctx, nil, "echo", "hello", "world"
Execute(ctx, nil, "bash", "-c", "echo 'hello world'"

func HashDir

func HashDir(pathToDir string) (string, error)

Returns a unique hash based on the contents of any "*.sql" files found in the specified directory.

func HashDirs

func HashDirs(base fs.FS, pattern string, dirs ...string) (string, error)

HashDirs will return as unique hash based on the contents of all files that match a given pattern, from any of the given directories. If `base` is nil, it will read the directories and files from the real file system.

Examples:

HashDirs(nil, "*.sql", "migrations")
HashDirs(nil, "*.sql", "migrations/old", "migrations/current")
HashDirs(embeddedFS, "*.sql", ".")

func HashFile

func HashFile(pathToFile string) (string, error)

Returns a unique hash based on the contents of the specified file.

func HashFiles

func HashFiles(base fs.FS, paths ...string) (string, error)

HashFiles will return as unique hash based on the contents of the specified files. If `base` is nil, it will read the paths from the real file system.

Examples:

HashFiles(nil, "0001_initial.sql")
HashFiles(nil, "0001_initial.sql", "0002_users.up.sql")
HashDirs(embeddedFS, "migrations/0001_initial.sql")

Types

type HashField

type HashField struct {
	Key   string
	Value any
}

HashField is a convenience type, you should create them with Field.

func Field

func Field(key string, value any) HashField

Field is a helper for incorporating certain settings/config values into a Hash() function result. You should hash.Add(Field(key, val)) any configuration settings that affect the final schema of a database, so that if those settings change the database template gets recreated.

type RecursiveHash

type RecursiveHash struct {
	hashlib.Hash
}

RecursiveHash is a small wrapper around an md5 hash. Each time more data is added to the hash, it will update itself to include the hash of all previous contents. This is good for hashing multiple migration files. The interface is slightly easier to use than constructing an md5 hash on your own.

func NewRecursiveHash

func NewRecursiveHash(fields ...HashField) RecursiveHash

NewRecursiveHash creates a new RecursiveHash, and adds any of the given fields to it.

Example:

hash, _ := NewRecursiveHash()
_ = hash.AddField(Field("CreateMigrationsTable", settings.CreateMigrationsTable))
_ = hash.AddField(Field("MigrationsTableName", settings.MigrationsTableName))
_ = hash.Add([]byte("hello"))
_ = hash.Add([]byte("world"))
out, _ := hash.String()

func (RecursiveHash) Add

func (h RecursiveHash) Add(bytes []byte)

Add updates the hash with the hash of new content.

func (RecursiveHash) AddDirs

func (h RecursiveHash) AddDirs(base fs.FS, pattern string, dirs ...string) error

func (RecursiveHash) AddField

func (h RecursiveHash) AddField(key string, value any)

AddField updates the hash with the hash of a new field.

func (RecursiveHash) AddFields

func (h RecursiveHash) AddFields(fields ...HashField)

AddFields updates the hash with the hash of multiple fields at once.

func (RecursiveHash) AddFiles

func (h RecursiveHash) AddFiles(base fs.FS, paths ...string) error

func (RecursiveHash) String

func (h RecursiveHash) String() string