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.