migrable
Updated
On this page

"migrable provides declarative, comment-preserving TOML config file migrations with 14 operations, rollback support, and an embeddable Go library for shipping migrations inside your binary."

#migrable

migrable provides declarative, comment-preserving TOML config file migrations with 14 operations, rollback support, and an embeddable Go library for shipping migrations inside your binary.

#API Reference

#config

#config

#Config

go
type Config struct

#Load

go
func Load(configDir string) (*Config, error)

#engine

#engine

#MigrationMeta

go
type MigrationMeta struct

#MigrateResult

go
type MigrateResult struct

MigrateResult holds the outcome of a Migrate call.

#RollbackBlockedError

go
type RollbackBlockedError struct

RollbackBlockedError is returned when a rollback cannot proceed because one or more ops are marked as irreversible.

#ValidationIssue

go
type ValidationIssue struct

ValidationIssue describes a single problem found during validation.

#ValidationResult

go
type ValidationResult struct

ValidationResult collects all errors and warnings from validation.

#DiscoverMigrations

go
func DiscoverMigrations(migrationsDir string) ([]MigrationMeta, error)

#WriteFilesAtomic

go
func WriteFilesAtomic(files map[string][]byte) error

WriteFilesAtomic writes multiple files transactionally. All files are first written to temp files in the same directories as their targets. Only after all temp files are written successfully are they renamed to their final paths. On any failure, all temp files are cleaned up.

#WriteFileAtomic

go
func WriteFileAtomic(path string, data []byte) error

#Init

go
func Init(dir string) error

Init scaffolds a new migrable project in the given directory. It creates migrable.toml, the migrations directory, and a next/ staging directory.

#Merge

go
func Merge(migrationsDir string, version string) (string, error)

Merge combines staging files from next/ into a single versioned migration file. Returns the output file path.

#Migrate

go
func Migrate(cfg *config.Config, dryRun bool) (*MigrateResult, error)

Migrate applies all pending migrations to the target file(s).

#Rollback

go
func Rollback(cfg *config.Config, dryRun bool) (*MigrateResult, error)

Rollback reverses the most recently applied migration.

#SplitFileKey

go
func SplitFileKey(path string, fileKeys []string) (fileKey string, innerPath string, err error)

SplitFileKey splits a dot-separated path into a file key and the inner path within that file. For single-file projects (one key), the full path is returned unchanged as the inner path. For multi-file projects, the first unescaped dot segment must match one of the file keys.

#Validate

go
func Validate(migrationsDir string) (*ValidationResult, error)

Validate checks all migration files in migrationsDir (and next/ if it exists) for correctness. It collects all issues rather than stopping at the first.

#ReadSchemaVersion

go
func ReadSchemaVersion(filePath string) (*semver.Version, error)

#WriteSchemaVersion

go
func WriteSchemaVersion(filePath string, version *semver.Version) error

#RollbackBlockedError.Error

go
func (e *RollbackBlockedError) Error() string

#ops

#ops

Package ops implements the 14 migration operations.

#MatchSubset

go
const MatchSubset    MatchMode = "subset"

#MatchExact

go
const MatchExact     MatchMode = "exact"

#MatchAll

go
const MatchAll       MatchMode = "all"

#MatchIndex

go
const MatchIndex     MatchMode = "index"

#MatchHasKey

go
const MatchHasKey    MatchMode = "has_key"

#MatchNotHasKey

go
const MatchNotHasKey MatchMode = "not_has_key"

#MatchRegex

go
const MatchRegex     MatchMode = "regex"

#OpAddField

go
const OpAddField          OpType = "add_field"

#OpRemoveField

go
const OpRemoveField       OpType = "remove_field"

#OpRenameField

go
const OpRenameField       OpType = "rename_field"

#OpMoveField

go
const OpMoveField         OpType = "move_field"

#OpAddCollection

go
const OpAddCollection     OpType = "add_collection"

#OpDropCollection

go
const OpDropCollection    OpType = "drop_collection"

#OpSetValue

go
const OpSetValue          OpType = "set_value"

#OpSetValueWhere

go
const OpSetValueWhere     OpType = "set_value_where"

#OpRemoveWhere

go
const OpRemoveWhere       OpType = "remove_where"

#OpAppend

go
const OpAppend            OpType = "append"

#OpTransform

go
const OpTransform         OpType = "transform"

#OpMergeDefaults

go
const OpMergeDefaults     OpType = "merge_defaults"

#OpMergeDefaultsByKey

go
const OpMergeDefaultsByKey OpType = "merge_defaults_by_key"

#OpRaw

go
const OpRaw               OpType = "raw"

#MatchMode

go
type MatchMode string

#Migration

go
type Migration struct

#OpType

go
type OpType string

#Op

go
type Op struct

#DownOp

go
type DownOp struct

#ExecSetValue

go
func ExecSetValue(doc *tomledit.DocumentNode, op Op) error

#ExecSetValueWhere

go
func ExecSetValueWhere(doc *tomledit.DocumentNode, op Op) error

#ExecRemoveWhere

go
func ExecRemoveWhere(doc *tomledit.DocumentNode, op Op) error

#ExecAppend

go
func ExecAppend(doc *tomledit.DocumentNode, op Op) error

#ExecMergeDefaults

go
func ExecMergeDefaults(doc *tomledit.DocumentNode, op Op) error

#ExecMergeDefaultsByKey

go
func ExecMergeDefaultsByKey(doc *tomledit.DocumentNode, op Op) error

#Execute

go
func Execute(doc *tomledit.DocumentNode, op Op) error

#Matches

go
func Matches(item map[string]any, where any, mode MatchMode, index int, arrayLen int) bool

Matches checks whether item matches the where clause according to the given mode. arrayLen is the total array length, needed for negative index normalization. index is the current element's position in the array.

#ParseMigration

go
func ParseMigration(data []byte) (*Migration, error)

#ExecRaw

go
func ExecRaw(doc *tomledit.DocumentNode, op Op) error

#ExecAddField

go
func ExecAddField(doc *tomledit.DocumentNode, op Op) error

#ExecRemoveField

go
func ExecRemoveField(doc *tomledit.DocumentNode, op Op) error

#ExecRenameField

go
func ExecRenameField(doc *tomledit.DocumentNode, op Op) error

#ExecMoveField

go
func ExecMoveField(doc *tomledit.DocumentNode, op Op) error

#ExecAddCollection

go
func ExecAddCollection(doc *tomledit.DocumentNode, op Op) error

#ExecDropCollection

go
func ExecDropCollection(doc *tomledit.DocumentNode, op Op) error

#ExecTransform

go
func ExecTransform(doc *tomledit.DocumentNode, op Op) error

#Op Types

Op Types
FieldTypeTagDescription
TypeOpType
Sectionstring"structure" or "data"
PathstringCommon
Down*DownOp
FieldTypestring"type" field from TOML
Defaultany
Fromstringrename_field, move_field
Tostring
Fieldsmap[string]anyadd_collection
Valueanyset_value, raw
Contentstring
Whereanyset_value_where, remove_where
MatchModestring
Setmap[string]any
Exprstringtransform
MatchFieldstringmerge_defaults_by_key
Defaults[]map[string]any

#CLI

See the README for the CLI command reference.