#migrable

Declarative config file migrations for TOML.

#API Reference

#config

#config

#Config

type Config struct

#Load

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

#engine

#engine

#MigrationMeta

type MigrationMeta struct

#MigrateResult

type MigrateResult struct

MigrateResult holds the outcome of a Migrate call.

#RollbackBlockedError

type RollbackBlockedError struct

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

#ValidationIssue

type ValidationIssue struct

ValidationIssue describes a single problem found during validation.

#ValidationResult

type ValidationResult struct

ValidationResult collects all errors and warnings from validation.

#DiscoverMigrations

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

#WriteFilesAtomic

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

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

#Init

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

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

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

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

#Rollback

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

Rollback reverses the most recently applied migration.

#SplitFileKey

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

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

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

#WriteSchemaVersion

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

#RollbackBlockedError.Error

func (e *RollbackBlockedError) Error() string

#ops

#ops

Package ops implements the 14 migration operations.

#MatchSubset

const MatchSubset    MatchMode = "subset"

#MatchExact

const MatchExact     MatchMode = "exact"

#MatchAll

const MatchAll       MatchMode = "all"

#MatchIndex

const MatchIndex     MatchMode = "index"

#MatchHasKey

const MatchHasKey    MatchMode = "has_key"

#MatchNotHasKey

const MatchNotHasKey MatchMode = "not_has_key"

#MatchRegex

const MatchRegex     MatchMode = "regex"

#OpAddField

const OpAddField          OpType = "add_field"

#OpRemoveField

const OpRemoveField       OpType = "remove_field"

#OpRenameField

const OpRenameField       OpType = "rename_field"

#OpMoveField

const OpMoveField         OpType = "move_field"

#OpAddCollection

const OpAddCollection     OpType = "add_collection"

#OpDropCollection

const OpDropCollection    OpType = "drop_collection"

#OpSetValue

const OpSetValue          OpType = "set_value"

#OpSetValueWhere

const OpSetValueWhere     OpType = "set_value_where"

#OpRemoveWhere

const OpRemoveWhere       OpType = "remove_where"

#OpAppend

const OpAppend            OpType = "append"

#OpTransform

const OpTransform         OpType = "transform"

#OpMergeDefaults

const OpMergeDefaults     OpType = "merge_defaults"

#OpMergeDefaultsByKey

const OpMergeDefaultsByKey OpType = "merge_defaults_by_key"

#OpRaw

const OpRaw               OpType = "raw"

#MatchMode

type MatchMode string

#Migration

type Migration struct

#OpType

type OpType string

#Op

type Op struct

#DownOp

type DownOp struct

#ExecSetValue

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

#ExecSetValueWhere

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

#ExecRemoveWhere

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

#ExecAppend

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

#ExecMergeDefaults

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

#ExecMergeDefaultsByKey

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

#Execute

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

#Matches

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

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

#ExecRaw

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

#ExecAddField

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

#ExecRemoveField

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

#ExecRenameField

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

#ExecMoveField

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

#ExecAddCollection

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

#ExecDropCollection

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

#ExecTransform

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

#Op Types

#CLI

See the README for the CLI command reference.