Documentation
¶
Overview ¶
jsonl_loader.go provides a JSONL file reader for loading row data into UpsertData migration operations.
operations.go defines the Operation interface and all concrete migration operation types used by the morphic Go migration framework.
Package migrate provides the runtime library for the morphic Go migration framework. Generated migration files import this package and call Register() in their init() functions.
Index ¶
- func BuildProviderFromType(dbType string) (providers.Provider, error)
- func EnvOr(name, defaultVal string) string
- func FormatLiteral(v any) string
- func Register(m *Migration)
- func RenderDAGASCII(out *DAGOutput) string
- func SortedKeys(m map[string]any) []string
- type AddField
- func (op *AddField) Describe() string
- func (op *AddField) Down(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
- func (op *AddField) IsDestructive() bool
- func (op *AddField) Mutate(state *SchemaState) error
- func (op *AddField) ShouldIgnoreErrors() bool
- func (op *AddField) TableName() string
- func (op *AddField) TypeName() string
- func (op *AddField) Up(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
- type AddForeignKey
- func (op *AddForeignKey) Describe() string
- func (op *AddForeignKey) Down(p providers.Provider, _ *SchemaState, _ map[string]string, _ string) (string, error)
- func (op *AddForeignKey) IsDestructive() bool
- func (op *AddForeignKey) Mutate(state *SchemaState) error
- func (op *AddForeignKey) ShouldIgnoreErrors() bool
- func (op *AddForeignKey) TableName() string
- func (op *AddForeignKey) TypeName() string
- func (op *AddForeignKey) Up(p providers.Provider, _ *SchemaState, _ map[string]string, _ string) (string, error)
- type AddIndex
- func (op *AddIndex) Describe() string
- func (op *AddIndex) Down(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
- func (op *AddIndex) IsDestructive() bool
- func (op *AddIndex) Mutate(state *SchemaState) error
- func (op *AddIndex) ShouldIgnoreErrors() bool
- func (op *AddIndex) TableName() string
- func (op *AddIndex) TypeName() string
- func (op *AddIndex) Up(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
- type AlterField
- func (op *AlterField) Describe() string
- func (op *AlterField) Down(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
- func (op *AlterField) IsDestructive() bool
- func (op *AlterField) Mutate(state *SchemaState) error
- func (op *AlterField) TableName() string
- func (op *AlterField) TypeName() string
- func (op *AlterField) Up(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
- type App
- type Config
- type CreateTable
- func (op *CreateTable) Describe() string
- func (op *CreateTable) Down(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
- func (op *CreateTable) IsDestructive() bool
- func (op *CreateTable) Mutate(state *SchemaState) error
- func (op *CreateTable) ShouldIgnoreErrors() bool
- func (op *CreateTable) TableName() string
- func (op *CreateTable) TypeName() string
- func (op *CreateTable) Up(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
- type DAGOutput
- type DefaultRef
- type DropField
- func (op *DropField) Describe() string
- func (op *DropField) Down(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
- func (op *DropField) IsDestructive() bool
- func (op *DropField) Mutate(state *SchemaState) error
- func (op *DropField) ShouldIgnoreErrors() bool
- func (op *DropField) TableName() string
- func (op *DropField) TypeName() string
- func (op *DropField) Up(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
- type DropForeignKey
- func (op *DropForeignKey) Describe() string
- func (op *DropForeignKey) Down(p providers.Provider, state *SchemaState, _ map[string]string, _ string) (string, error)
- func (op *DropForeignKey) IsDestructive() bool
- func (op *DropForeignKey) Mutate(state *SchemaState) error
- func (op *DropForeignKey) ShouldIgnoreErrors() bool
- func (op *DropForeignKey) TableName() string
- func (op *DropForeignKey) TypeName() string
- func (op *DropForeignKey) Up(p providers.Provider, _ *SchemaState, _ map[string]string, _ string) (string, error)
- type DropIndex
- func (op *DropIndex) Describe() string
- func (op *DropIndex) Down(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
- func (op *DropIndex) IsDestructive() bool
- func (op *DropIndex) Mutate(state *SchemaState) error
- func (op *DropIndex) ShouldIgnoreErrors() bool
- func (op *DropIndex) TableName() string
- func (op *DropIndex) TypeName() string
- func (op *DropIndex) Up(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
- type DropTable
- func (op *DropTable) Describe() string
- func (op *DropTable) Down(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
- func (op *DropTable) IsDestructive() bool
- func (op *DropTable) Mutate(state *SchemaState) error
- func (op *DropTable) ShouldIgnoreErrors() bool
- func (op *DropTable) TableName() string
- func (op *DropTable) TypeName() string
- func (op *DropTable) Up(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
- type ErrorIgnorer
- type Field
- type ForeignKey
- type ForeignKeyConstraint
- type Graph
- func (g *Graph) DetectBranches() [][]string
- func (g *Graph) HasBranches() bool
- func (g *Graph) Leaves() []string
- func (g *Graph) Linearize() ([]*Migration, error)
- func (g *Graph) ReconstructState() (*SchemaState, error)
- func (g *Graph) Roots() []string
- func (g *Graph) ToDAGOutput() (*DAGOutput, error)
- type Index
- type ManyToMany
- type Migration
- type MigrationRecorder
- func (r *MigrationRecorder) EnsureTable() error
- func (r *MigrationRecorder) Fake(name string) error
- func (r *MigrationRecorder) GetApplied() (map[string]bool, error)
- func (r *MigrationRecorder) RecordApplied(name string) error
- func (r *MigrationRecorder) RecordAppliedTx(tx *sql.Tx, name string) error
- func (r *MigrationRecorder) RecordRolledBack(name string) error
- func (r *MigrationRecorder) RecordRolledBackTx(tx *sql.Tx, name string) error
- type MigrationSummary
- type Operation
- type OperationSummary
- type Registry
- type RenameField
- func (op *RenameField) Describe() string
- func (op *RenameField) Down(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
- func (op *RenameField) IsDestructive() bool
- func (op *RenameField) Mutate(state *SchemaState) error
- func (op *RenameField) TableName() string
- func (op *RenameField) TypeName() string
- func (op *RenameField) Up(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
- type RenameTable
- func (op *RenameTable) Describe() string
- func (op *RenameTable) Down(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
- func (op *RenameTable) IsDestructive() bool
- func (op *RenameTable) Mutate(state *SchemaState) error
- func (op *RenameTable) TableName() string
- func (op *RenameTable) TypeName() string
- func (op *RenameTable) Up(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
- type RunOptions
- type RunSQL
- func (op *RunSQL) Describe() string
- func (op *RunSQL) Down(_ providers.Provider, _ *SchemaState, _ map[string]string, _ string) (string, error)
- func (op *RunSQL) IsDestructive() bool
- func (op *RunSQL) Mutate(_ *SchemaState) error
- func (op *RunSQL) TableName() string
- func (op *RunSQL) TypeName() string
- func (op *RunSQL) Up(_ providers.Provider, _ *SchemaState, _ map[string]string, _ string) (string, error)
- type Runner
- type SchemaState
- func (s *SchemaState) AddField(tableName string, field Field) error
- func (s *SchemaState) AddForeignKey(tableName string, fk ForeignKeyConstraint) error
- func (s *SchemaState) AddIndex(tableName string, index Index) error
- func (s *SchemaState) AddTable(name string, fields []Field, indexes []Index) error
- func (s *SchemaState) AlterField(tableName string, newField Field) error
- func (s *SchemaState) DropField(tableName, fieldName string) error
- func (s *SchemaState) DropForeignKey(tableName, constraintName string) error
- func (s *SchemaState) DropIndex(tableName, indexName string) error
- func (s *SchemaState) DropTable(name string) error
- func (s *SchemaState) RenameField(tableName, oldName, newName string) error
- func (s *SchemaState) RenameTable(oldName, newName string) error
- func (s *SchemaState) SetDefaults(defaults map[string]string)
- func (s *SchemaState) SetTypeMappings(m map[string]string)
- type SetDefaults
- func (op *SetDefaults) Describe() string
- func (op *SetDefaults) Down(_ providers.Provider, _ *SchemaState, _ map[string]string, _ string) (string, error)
- func (op *SetDefaults) IsDestructive() bool
- func (op *SetDefaults) Mutate(state *SchemaState) error
- func (op *SetDefaults) TableName() string
- func (op *SetDefaults) TypeName() string
- func (op *SetDefaults) Up(_ providers.Provider, _ *SchemaState, _ map[string]string, _ string) (string, error)
- type SetTypeMappings
- func (op *SetTypeMappings) Describe() string
- func (op *SetTypeMappings) Down(_ providers.Provider, _ *SchemaState, _ map[string]string, _ string) (string, error)
- func (op *SetTypeMappings) IsDestructive() bool
- func (op *SetTypeMappings) Mutate(state *SchemaState) error
- func (op *SetTypeMappings) TableName() string
- func (op *SetTypeMappings) TypeName() string
- func (op *SetTypeMappings) Up(_ providers.Provider, _ *SchemaState, _ map[string]string, _ string) (string, error)
- type TableState
- type UpsertData
- func (op *UpsertData) Describe() string
- func (op *UpsertData) Down(p providers.Provider, _ *SchemaState, _ map[string]string, ...) (string, error)
- func (op *UpsertData) IsDestructive() bool
- func (op *UpsertData) Mutate(_ *SchemaState) error
- func (op *UpsertData) TableName() string
- func (op *UpsertData) TypeName() string
- func (op *UpsertData) Up(p providers.Provider, _ *SchemaState, defaults map[string]string, ...) (string, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildProviderFromType ¶
BuildProviderFromType creates a Provider from a database type string. It delegates to providers.NewProvider which supports all registered database types (postgresql, mysql, sqlite, sqlserver, etc.).
func EnvOr ¶
EnvOr returns the value of the named environment variable, or defaultVal if the variable is not set or empty.
func FormatLiteral ¶
FormatLiteral converts a Go value into a SQL literal string suitable for embedding directly in a SQL statement. It is used by UpsertData.Up to pre-format row values before passing them to the provider's GenerateUpsert. DefaultRef values are NOT handled here — they are resolved in UpsertData.Up before FormatLiteral is called.
Supported types:
- nil → NULL
- string → 'value' (single quotes escaped as ”)
- bool → TRUE / FALSE
- int variants → decimal literal
- uint variants → decimal literal
- float32/float64 → decimal literal (strconv.FormatFloat, 'f' format)
- time.Time → 'YYYY-MM-DD HH:MM:SS'
- fmt.Stringer → quoted using the Stringer output
- everything else → quoted using fmt.Sprintf("%v")
func Register ¶
func Register(m *Migration)
Register adds a migration to the global registry. Called by each generated migration file's init() function. Panics on duplicates.
func RenderDAGASCII ¶
RenderDAGASCII produces a human-readable ASCII tree of the migration graph. It uses box-drawing characters to show parent->child relationships.
func SortedKeys ¶
SortedKeys returns the keys of the map in alphabetical order. Used by UpsertData.Up to establish a consistent column ordering across rows.
Types ¶
type AddField ¶
type AddField struct {
Table string
Field Field
SchemaOnly bool // when true, Up/Down return no SQL; Mutate still runs
IgnoreErrors bool // when true, runner logs a warning and continues on SQL failure
}
AddField is a migration operation that adds a new column to an existing table. When SchemaOnly is true the operation advances the in-memory schema state (via Mutate) but does not execute any SQL, allowing the schema state to be seeded from an existing database without running ALTER TABLE ADD COLUMN.
func (*AddField) Down ¶
func (op *AddField) Down(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
Down generates the DROP COLUMN SQL to reverse the addition. Returns empty string when SchemaOnly is set.
func (*AddField) IsDestructive ¶
IsDestructive returns false — adding a column is not destructive.
func (*AddField) Mutate ¶
func (op *AddField) Mutate(state *SchemaState) error
Mutate adds the new field to the table's entry in SchemaState.
func (*AddField) ShouldIgnoreErrors ¶ added in v1.14.1
ShouldIgnoreErrors implements ErrorIgnorer.
func (*AddField) Up ¶
func (op *AddField) Up(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
Up generates the ADD COLUMN SQL statement, or returns empty string when SchemaOnly is set. The field default is resolved against the active defaults map before being passed to the provider.
type AddForeignKey ¶
type AddForeignKey struct {
Table string
FieldName string
ConstraintName string
ReferencedTable string
OnDelete string
OnUpdate string
IgnoreErrors bool // when true, runner logs a warning and continues on SQL failure
}
AddForeignKey is a migration operation that adds a foreign key constraint to an existing table using ALTER TABLE ... ADD CONSTRAINT ... FOREIGN KEY. The FK column must already exist (created by AddField or CreateTable).
func (*AddForeignKey) Describe ¶
func (op *AddForeignKey) Describe() string
Describe returns a human-readable description of this operation.
func (*AddForeignKey) Down ¶
func (op *AddForeignKey) Down(p providers.Provider, _ *SchemaState, _ map[string]string, _ string) (string, error)
Down generates the ALTER TABLE ... DROP CONSTRAINT SQL to remove the FK.
func (*AddForeignKey) IsDestructive ¶
func (op *AddForeignKey) IsDestructive() bool
IsDestructive returns false — adding a FK constraint is not destructive.
func (*AddForeignKey) Mutate ¶
func (op *AddForeignKey) Mutate(state *SchemaState) error
Mutate records the foreign key in the SchemaState.
func (*AddForeignKey) ShouldIgnoreErrors ¶
func (op *AddForeignKey) ShouldIgnoreErrors() bool
ShouldIgnoreErrors implements ErrorIgnorer.
func (*AddForeignKey) TableName ¶
func (op *AddForeignKey) TableName() string
TableName returns the name of the table the constraint is added to.
func (*AddForeignKey) TypeName ¶
func (op *AddForeignKey) TypeName() string
TypeName returns the operation type identifier.
func (*AddForeignKey) Up ¶
func (op *AddForeignKey) Up(p providers.Provider, _ *SchemaState, _ map[string]string, _ string) (string, error)
Up generates the ALTER TABLE ... ADD CONSTRAINT ... FOREIGN KEY SQL. Django-style on_delete values are normalised to their SQL equivalents:
- PROTECT → RESTRICT (Django raises ProtectedError; SQL enforces at DB level)
- SET_NULL → SET NULL
- SET_DEFAULT → SET DEFAULT
- DO_NOTHING → NO ACTION
type AddIndex ¶
type AddIndex struct {
Table string
Index Index
IgnoreErrors bool // when true, runner logs a warning and continues on SQL failure
}
AddIndex is a migration operation that adds an index to an existing table.
func (*AddIndex) Down ¶
func (op *AddIndex) Down(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
Down generates the DROP INDEX SQL to reverse the index creation.
func (*AddIndex) IsDestructive ¶
IsDestructive returns false — adding an index is not destructive.
func (*AddIndex) Mutate ¶
func (op *AddIndex) Mutate(state *SchemaState) error
Mutate adds the index to the table's entry in SchemaState.
func (*AddIndex) ShouldIgnoreErrors ¶ added in v1.14.1
ShouldIgnoreErrors implements ErrorIgnorer.
type AlterField ¶
AlterField is a migration operation that modifies an existing column's definition.
func (*AlterField) Describe ¶
func (op *AlterField) Describe() string
Describe returns a human-readable description of this operation.
func (*AlterField) Down ¶
func (op *AlterField) Down(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
Down generates the ALTER COLUMN SQL to restore the original field definition. If the provider implements TableRecreationProvider (e.g. SQLite), the full current table definition is passed so the provider can recreate the table. Field defaults are resolved against the active defaults map before use.
func (*AlterField) IsDestructive ¶
func (op *AlterField) IsDestructive() bool
IsDestructive returns false — altering a column is not considered destructive (though data conversion may fail at the database level for incompatible types).
func (*AlterField) Mutate ¶
func (op *AlterField) Mutate(state *SchemaState) error
Mutate replaces the field in the table's entry in SchemaState.
func (*AlterField) TableName ¶
func (op *AlterField) TableName() string
TableName returns the name of the table being altered.
func (*AlterField) TypeName ¶
func (op *AlterField) TypeName() string
TypeName returns the operation type identifier.
func (*AlterField) Up ¶
func (op *AlterField) Up(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
Up generates the ALTER COLUMN SQL to apply the new field definition. If the provider implements TableRecreationProvider (e.g. SQLite), the full current table definition is passed so the provider can recreate the table. Field defaults are resolved against the active defaults map before use.
type App ¶
type App struct {
// contains filtered or unexported fields
}
App is the CLI application embedded in each compiled migration binary.
func NewApp ¶
NewApp creates a new App with the given configuration. It uses the global registry by default.
func NewAppWithRegistry ¶
NewAppWithRegistry creates a new App with the given configuration and a specific registry. This is primarily useful for testing.
type Config ¶
type Config struct {
DatabaseType string // postgresql, mysql, sqlserver, sqlite
DatabaseURL string // full DSN — overrides individual fields if set
DBHost string
DBPort string
DBUser string
DBPassword string
DBName string
DBSSLMode string
MigrationsDir string // path to migrations directory, for resolving external data files
}
Config holds database connection configuration for the migration binary. All fields default to environment variables if not set explicitly.
type CreateTable ¶
type CreateTable struct {
Name string
Fields []Field
Indexes []Index
SchemaOnly bool // when true, Up/Down return no SQL; Mutate still runs
IgnoreErrors bool // when true, runner logs a warning and continues on SQL failure
}
CreateTable is a migration operation that creates a new database table with the specified fields and indexes. When SchemaOnly is true the operation advances the in-memory schema state (via Mutate) but does not execute any SQL, allowing the schema state to be seeded from an existing database without re-running CREATE TABLE.
func (*CreateTable) Describe ¶
func (op *CreateTable) Describe() string
Describe returns a human-readable description of this operation.
func (*CreateTable) Down ¶
func (op *CreateTable) Down(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
Down generates the DROP TABLE CASCADE SQL to reverse the creation. Uses GenerateDropTableCascade so that any dependent objects (e.g. foreign key constraints from other tables) are automatically removed, preventing ordering failures when multiple CreateTable operations are rolled back together. Returns empty string when SchemaOnly is set.
func (*CreateTable) IsDestructive ¶
func (op *CreateTable) IsDestructive() bool
IsDestructive returns false — creating a table is not destructive.
func (*CreateTable) Mutate ¶
func (op *CreateTable) Mutate(state *SchemaState) error
Mutate adds the new table to the SchemaState.
func (*CreateTable) ShouldIgnoreErrors ¶
func (op *CreateTable) ShouldIgnoreErrors() bool
ShouldIgnoreErrors implements ErrorIgnorer.
func (*CreateTable) TableName ¶
func (op *CreateTable) TableName() string
TableName returns the name of the table being created.
func (*CreateTable) TypeName ¶
func (op *CreateTable) TypeName() string
TypeName returns the operation type identifier.
func (*CreateTable) Up ¶
func (op *CreateTable) Up(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
Up generates the CREATE TABLE SQL statement, or returns empty string when SchemaOnly is set. Field defaults are resolved against the active defaults map before being passed to the provider.
type DAGOutput ¶
type DAGOutput struct {
Migrations []MigrationSummary `json:"migrations"`
Roots []string `json:"roots"`
Leaves []string `json:"leaves"`
HasBranches bool `json:"has_branches"`
HasUnresolvedBranches bool `json:"has_unresolved_branches"`
SchemaState *SchemaState `json:"schema_state"`
}
DAGOutput is the JSON-serialisable representation of the full migration graph. This is what the compiled migration binary emits via the `dag --format json` command.
type DefaultRef ¶
type DefaultRef string
DefaultRef is a string type that marks a row value as a reference to a named schema default rather than a literal value. When UpsertData.Up encounters a DefaultRef it resolves the key through the active defaults map (set by the SetDefaults operation) and emits the resolved SQL expression verbatim — without quoting it as a string literal.
If the key is not present in the defaults map, the key itself is emitted as a raw SQL expression (useful for calling built-in functions directly, e.g. DefaultRef("NOW()") or DefaultRef("gen_random_uuid()")).
Example:
&m.UpsertData{
Table: "items",
ConflictKeys: []string{"code"},
Rows: []map[string]any{
{"id": m.DefaultRef("uuid"), "code": "AU", "name": "Australia"},
},
}
With SetDefaults{"uuid": "uuid_generate_v4()"} active this produces:
INSERT INTO "items" ("code", "id", "name")
VALUES ('AU', uuid_generate_v4(), 'Australia')
ON CONFLICT ("code") DO UPDATE SET ...
type DropField ¶
type DropField struct {
Table string
Field string
SchemaOnly bool // when true, Up/Down return no SQL; Mutate still runs
IgnoreErrors bool // when true, runner logs a warning and continues on SQL failure
}
DropField is a migration operation that removes a column from an existing table. When SchemaOnly is true the operation advances the in-memory schema state (via Mutate) but does not execute any SQL against the database, allowing the developer to acknowledge a removal in the schema definition without immediately dropping the live column.
func (*DropField) Down ¶
func (op *DropField) Down(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
Down reconstructs the ADD COLUMN SQL by reading the field's pre-drop state. Returns empty string when SchemaOnly is set. The field default is resolved against the active defaults map before being passed to the provider.
func (*DropField) IsDestructive ¶
IsDestructive returns true — dropping a column causes data loss.
func (*DropField) Mutate ¶
func (op *DropField) Mutate(state *SchemaState) error
Mutate removes the field from the table's entry in SchemaState.
func (*DropField) ShouldIgnoreErrors ¶
ShouldIgnoreErrors implements ErrorIgnorer.
type DropForeignKey ¶
type DropForeignKey struct {
Table string
ConstraintName string
IgnoreErrors bool // when true, runner logs a warning and continues on SQL failure
}
DropForeignKey is a migration operation that drops a foreign key constraint from an existing table using ALTER TABLE ... DROP CONSTRAINT. The Down method reads the pre-drop FK definition from SchemaState to reconstruct the ADD CONSTRAINT SQL — state must still contain the FK when Down is called (i.e. before Mutate runs, which is the runner's guarantee).
func (*DropForeignKey) Describe ¶
func (op *DropForeignKey) Describe() string
Describe returns a human-readable description of this operation.
func (*DropForeignKey) Down ¶
func (op *DropForeignKey) Down(p providers.Provider, state *SchemaState, _ map[string]string, _ string) (string, error)
Down reconstructs the ADD CONSTRAINT SQL by reading the FK's pre-drop state.
func (*DropForeignKey) IsDestructive ¶
func (op *DropForeignKey) IsDestructive() bool
IsDestructive returns true — removing a FK constraint changes referential integrity.
func (*DropForeignKey) Mutate ¶
func (op *DropForeignKey) Mutate(state *SchemaState) error
Mutate removes the foreign key from the SchemaState.
func (*DropForeignKey) ShouldIgnoreErrors ¶
func (op *DropForeignKey) ShouldIgnoreErrors() bool
ShouldIgnoreErrors implements ErrorIgnorer.
func (*DropForeignKey) TableName ¶
func (op *DropForeignKey) TableName() string
TableName returns the name of the table the constraint is removed from.
func (*DropForeignKey) TypeName ¶
func (op *DropForeignKey) TypeName() string
TypeName returns the operation type identifier.
type DropIndex ¶
type DropIndex struct {
Table string
Index string
IgnoreErrors bool // when true, runner logs a warning and continues on SQL failure
}
DropIndex is a migration operation that removes an index from an existing table.
func (*DropIndex) Down ¶
func (op *DropIndex) Down(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
Down reconstructs the CREATE INDEX SQL by reading the index's pre-drop state.
func (*DropIndex) IsDestructive ¶
IsDestructive returns false — dropping an index is not considered destructive.
func (*DropIndex) Mutate ¶
func (op *DropIndex) Mutate(state *SchemaState) error
Mutate removes the index from the table's entry in SchemaState.
func (*DropIndex) ShouldIgnoreErrors ¶
ShouldIgnoreErrors implements ErrorIgnorer.
type DropTable ¶
type DropTable struct {
Name string
SchemaOnly bool // when true, Up/Down return no SQL; Mutate still runs
IgnoreErrors bool // when true, runner logs a warning and continues on SQL failure
}
DropTable is a migration operation that drops an existing database table. When SchemaOnly is true the operation advances the in-memory schema state (via Mutate) but does not execute any SQL against the database, allowing the developer to acknowledge a removal in the schema definition without immediately dropping the live table.
func (*DropTable) Down ¶
func (op *DropTable) Down(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
Down reconstructs the CREATE TABLE SQL by reading the table's pre-drop state. Returns empty string when SchemaOnly is set.
func (*DropTable) IsDestructive ¶
IsDestructive returns true — dropping a table causes data loss.
func (*DropTable) Mutate ¶
func (op *DropTable) Mutate(state *SchemaState) error
Mutate removes the table from the SchemaState.
func (*DropTable) ShouldIgnoreErrors ¶
ShouldIgnoreErrors implements ErrorIgnorer.
type ErrorIgnorer ¶
type ErrorIgnorer interface {
ShouldIgnoreErrors() bool
}
ErrorIgnorer is an optional interface implemented by operations that support ignoring execution errors at the runner level. When ShouldIgnoreErrors returns true, the runner logs a warning and continues instead of aborting.
type Field ¶
type Field struct {
Name string `json:"name"`
Type string `json:"type"` // varchar, text, integer, uuid, boolean, timestamp, foreign_key, etc.
PrimaryKey bool `json:"primary_key,omitempty"`
Nullable bool `json:"nullable,omitempty"`
Default string `json:"default,omitempty"` // default reference name e.g. "new_uuid", "now", "true"
Length int `json:"length,omitempty"` // for varchar
Precision int `json:"precision,omitempty"` // for decimal/numeric
Scale int `json:"scale,omitempty"` // for decimal/numeric
AutoCreate bool `json:"auto_create,omitempty"` // auto-set on row creation (created_at)
AutoUpdate bool `json:"auto_update,omitempty"` // auto-set on row update (updated_at)
ForeignKey *ForeignKey `json:"foreign_key,omitempty"`
ManyToMany *ManyToMany `json:"many_to_many,omitempty"`
}
Field represents a database column definition used in migration operations.
type ForeignKey ¶
type ForeignKey struct {
Table string `json:"table"`
OnDelete string `json:"on_delete,omitempty"`
OnUpdate string `json:"on_update,omitempty"`
}
ForeignKey represents a foreign key constraint.
type ForeignKeyConstraint ¶
type ForeignKeyConstraint struct {
Name string `json:"name"` // constraint name, e.g. fk_orders_user_id
FieldName string `json:"field_name"` // the column carrying the FK
ReferencedTable string `json:"referenced_table"`
OnDelete string `json:"on_delete,omitempty"`
OnUpdate string `json:"on_update,omitempty"`
}
ForeignKeyConstraint represents a FK constraint tracked in SchemaState. Note: this is distinct from migrate.ForeignKey (the field-level FK metadata). ForeignKeyConstraint tracks what constraints exist in the database at runtime.
type Graph ¶
type Graph struct {
// contains filtered or unexported fields
}
Graph is a directed acyclic graph (DAG) of migrations. Each node represents one migration; edges represent dependencies.
func BuildGraph ¶
BuildGraph constructs a Graph from a Registry. Returns an error if any dependency is missing or if a cycle is detected.
func (*Graph) DetectBranches ¶
DetectBranches returns groups of leaf migration names when there are multiple leaves (indicating concurrent development branches). Returns empty slice if the graph is linear.
func (*Graph) HasBranches ¶
HasBranches returns true if the graph contains any branching structure. This includes divergent branches (multiple leaves) and diamond topologies where a node has more than one child, even if the branches later converge.
func (*Graph) Leaves ¶
Leaves returns names of migrations that no other migration depends on (no children).
func (*Graph) Linearize ¶
Linearize returns all migrations in topological order using Kahn's algorithm. Deterministic: nodes at the same level are sorted by name.
func (*Graph) ReconstructState ¶
func (g *Graph) ReconstructState() (*SchemaState, error)
ReconstructState replays all operations in topological order to produce the full schema state as it would exist after all registered migrations have run.
func (*Graph) ToDAGOutput ¶
ToDAGOutput builds a DAGOutput from this graph, including the reconstructed schema state.
type Index ¶
type Index struct {
Name string `json:"name"`
Fields []string `json:"fields"`
Unique bool `json:"unique,omitempty"`
// Method specifies the index access method (e.g. BTREE, HASH, GIN, GIST, BRIN).
// Leave empty to use the database default. Not supported by SQLite or SQL Server.
Method string `json:"method,omitempty"`
// Where is a partial index predicate. Leave empty for a full index. Not supported by MySQL.
Where string `json:"where,omitempty"`
// FromFK marks indexes auto-generated for foreign key columns. These are
// managed automatically by AddForeignKey/DropForeignKey and excluded from
// schema diffs and generated migration code.
FromFK bool `json:"from_fk,omitempty"`
}
Index represents a database index definition.
type ManyToMany ¶
type ManyToMany struct {
Table string `json:"table"`
}
ManyToMany represents a many-to-many relationship via junction table.
type Migration ¶
type Migration struct {
Name string `json:"name"` // Unique identifier e.g. "0001_initial"
Dependencies []string `json:"dependencies"` // Names of migrations this depends on
Operations []Operation `json:"-"` // Ordered list of schema operations to apply
Replaces []string `json:"replaces,omitempty"` // For squashed migrations: names of migrations this replaces
Initial bool `json:"initial,omitempty"` // Marks this as an initial migration for --fake-initial support
}
Migration represents a single database migration with its name, dependencies, and operations.
type MigrationRecorder ¶
type MigrationRecorder struct {
// contains filtered or unexported fields
}
MigrationRecorder manages the morphic_history table. It records which migrations have been applied to the database.
func NewMigrationRecorder ¶
func NewMigrationRecorder(db *sql.DB, p providers.Provider) *MigrationRecorder
NewMigrationRecorder creates a new MigrationRecorder using the given db connection and provider. The provider supplies the database-specific DDL and placeholder style.
func (*MigrationRecorder) EnsureTable ¶
func (r *MigrationRecorder) EnsureTable() error
EnsureTable creates the morphic_history table if it does not exist. The DDL is supplied by the provider so it is correct for the target database.
func (*MigrationRecorder) Fake ¶
func (r *MigrationRecorder) Fake(name string) error
Fake inserts a migration name without executing any SQL. Used to mark migrations as applied when the database already has the schema.
func (*MigrationRecorder) GetApplied ¶
func (r *MigrationRecorder) GetApplied() (map[string]bool, error)
GetApplied returns a set of migration names that have been applied.
func (*MigrationRecorder) RecordApplied ¶
func (r *MigrationRecorder) RecordApplied(name string) error
RecordApplied inserts a migration name into the history table.
func (*MigrationRecorder) RecordAppliedTx ¶
func (r *MigrationRecorder) RecordAppliedTx(tx *sql.Tx, name string) error
RecordAppliedTx inserts a migration name into the history table within an existing transaction, so the history record is committed or rolled back atomically with the migration SQL.
func (*MigrationRecorder) RecordRolledBack ¶
func (r *MigrationRecorder) RecordRolledBack(name string) error
RecordRolledBack removes a migration name from the history table.
func (*MigrationRecorder) RecordRolledBackTx ¶
func (r *MigrationRecorder) RecordRolledBackTx(tx *sql.Tx, name string) error
RecordRolledBackTx removes a migration name from the history table within an existing transaction, so the history deletion is committed or rolled back atomically with the rollback SQL.
type MigrationSummary ¶
type MigrationSummary struct {
Name string `json:"name"`
Dependencies []string `json:"dependencies"`
Operations []OperationSummary `json:"operations"`
}
MigrationSummary is a JSON-serialisable summary of a single migration.
type Operation ¶
type Operation interface {
// Up generates the forward SQL for this operation.
Up(p providers.Provider, state *SchemaState, defaults map[string]string, migrationsDir string) (string, error)
// Down generates the reverse SQL to undo this operation.
Down(p providers.Provider, state *SchemaState, defaults map[string]string, migrationsDir string) (string, error)
// Mutate applies this operation to the given SchemaState, updating the
// in-memory schema representation during migration graph traversal.
Mutate(state *SchemaState) error
// Describe returns a human-readable description of the operation.
Describe() string
// TypeName returns the operation type identifier (e.g. "create_table").
TypeName() string
// TableName returns the primary table this operation acts on, or "" for RunSQL.
TableName() string
// IsDestructive returns true if this operation may cause data loss.
IsDestructive() bool
}
Operation is the interface all migration operations must implement. Each operation can generate forward (Up) and reverse (Down) SQL, mutate the in-memory SchemaState for graph traversal, and describe itself for display. Up/Down method names align with the CLI commands `./migrate up` / `./migrate down`.
type OperationSummary ¶
type OperationSummary struct {
Type string `json:"type"`
Table string `json:"table,omitempty"`
Description string `json:"description"`
}
OperationSummary is a JSON-serialisable summary of a single operation.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry stores all registered migrations, preserving insertion order.
func GlobalRegistry ¶
func GlobalRegistry() *Registry
GlobalRegistry returns the global registry. Used by app.go to build the migration graph.
func NewRegistry ¶
func NewRegistry() *Registry
NewRegistry creates an empty Registry. Used for testing; generated migration files use the global registry.
func (*Registry) Get ¶
Get returns a migration by name, and a boolean indicating whether it was found.
func (*Registry) Resolve ¶
Resolve validates that name matches a registered migration exactly and returns it. Returns an error if no migration with that exact name is registered. Exact matching is required so that "fake 0002" is rejected when multiple migrations share the same numeric prefix (e.g. 0002_add_users, 0002_add_orders).
type RenameField ¶
RenameField is a migration operation that renames a column in an existing table.
func (*RenameField) Describe ¶
func (op *RenameField) Describe() string
Describe returns a human-readable description of this operation.
func (*RenameField) Down ¶
func (op *RenameField) Down(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
Down generates the reverse RENAME COLUMN SQL to restore the original name.
func (*RenameField) IsDestructive ¶
func (op *RenameField) IsDestructive() bool
IsDestructive returns false — renaming a column is not destructive.
func (*RenameField) Mutate ¶
func (op *RenameField) Mutate(state *SchemaState) error
Mutate updates the field name in the table's entry in SchemaState.
func (*RenameField) TableName ¶
func (op *RenameField) TableName() string
TableName returns the name of the table being altered.
func (*RenameField) TypeName ¶
func (op *RenameField) TypeName() string
TypeName returns the operation type identifier.
type RenameTable ¶
type RenameTable struct{ OldName, NewName string }
RenameTable is a migration operation that renames an existing database table.
func (*RenameTable) Describe ¶
func (op *RenameTable) Describe() string
Describe returns a human-readable description of this operation.
func (*RenameTable) Down ¶
func (op *RenameTable) Down(p providers.Provider, state *SchemaState, defaults map[string]string, _ string) (string, error)
Down generates the reverse RENAME TABLE SQL to restore the original name.
func (*RenameTable) IsDestructive ¶
func (op *RenameTable) IsDestructive() bool
IsDestructive returns false — renaming a table is not destructive.
func (*RenameTable) Mutate ¶
func (op *RenameTable) Mutate(state *SchemaState) error
Mutate updates the SchemaState to reflect the renamed table.
func (*RenameTable) TableName ¶
func (op *RenameTable) TableName() string
TableName returns the old (pre-rename) table name.
func (*RenameTable) TypeName ¶
func (op *RenameTable) TypeName() string
TypeName returns the operation type identifier.
type RunOptions ¶
type RunOptions struct {
// WarnOnMissingDrop causes drop operations that fail because the target
// object does not exist to print a warning and continue rather than stop.
WarnOnMissingDrop bool
// FakeInitial causes migrations marked Initial=true to be faked (recorded
// as applied without running SQL) when all their CreateTable tables and
// columns already exist in the live database.
FakeInitial bool
}
RunOptions controls optional behaviour for Up and Down.
type RunSQL ¶
type RunSQL struct {
// ForwardSQL is the raw SQL to execute on Up (forward migration).
ForwardSQL string
// BackwardSQL is the raw SQL to execute on Down (reverse migration).
BackwardSQL string
// SchemaOnly marks the operation as applied without executing any SQL.
// Use this when the underlying schema already exists in the database.
SchemaOnly bool
}
RunSQL is a migration operation that executes raw SQL for forward and reverse migrations. ForwardSQL and BackwardSQL field names are used (not Forward/Backward) to avoid conflict with the Up/Down method names on the Operation interface. When SchemaOnly is true the operation is recorded as applied but no SQL is sent to the database — useful when the schema is already in place.
func (*RunSQL) Describe ¶
Describe returns a human-readable description of this operation. Includes a truncated preview of the SQL to aid debugging.
func (*RunSQL) Down ¶
func (op *RunSQL) Down(_ providers.Provider, _ *SchemaState, _ map[string]string, _ string) (string, error)
Down returns the BackwardSQL string, or empty string when SchemaOnly is set.
func (*RunSQL) IsDestructive ¶
IsDestructive returns false — RunSQL destructiveness depends on the SQL content.
func (*RunSQL) Mutate ¶
func (op *RunSQL) Mutate(_ *SchemaState) error
Mutate is a no-op for RunSQL — raw SQL does not alter the SchemaState.
func (*RunSQL) TableName ¶
TableName returns an empty string — RunSQL does not target a specific table.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner executes migrations against a database in topological order.
func NewRunner ¶
func NewRunner(graph *Graph, provider providers.Provider, db *sql.DB, recorder *MigrationRecorder, output io.Writer, migrationsDir string) *Runner
NewRunner creates a Runner using the given graph, provider, db, recorder, output writer, and migrationsDir. If output is nil, os.Stdout is used. migrationsDir is passed to operations so they can resolve external data files.
func (*Runner) Down ¶
func (r *Runner) Down(steps int, to string, opts RunOptions) error
Down rolls back migrations. If steps > 0, rolls back that many. If to is set, rolls back until that migration name is reached (exclusive).
type SchemaState ¶
type SchemaState struct {
Tables map[string]*TableState `json:"tables"`
Defaults map[string]string `json:"defaults,omitempty"` // active DB-type defaults from SetDefaults operations
TypeMappings map[string]string `json:"type_mappings,omitempty"` // active provider's type mappings from SetTypeMappings operations
}
SchemaState holds the in-memory representation of the database schema at a specific point in the migration graph. Operations call Mutate() to update it as they are applied during graph traversal.
func NewSchemaState ¶
func NewSchemaState() *SchemaState
NewSchemaState returns an empty SchemaState.
func (*SchemaState) AddField ¶
func (s *SchemaState) AddField(tableName string, field Field) error
AddField appends a field to an existing table. Returns error if the field name already exists.
func (*SchemaState) AddForeignKey ¶
func (s *SchemaState) AddForeignKey(tableName string, fk ForeignKeyConstraint) error
AddForeignKey appends a foreign key constraint to an existing table. If the constraint already exists it is updated in place (idempotent).
func (*SchemaState) AddIndex ¶
func (s *SchemaState) AddIndex(tableName string, index Index) error
AddIndex appends an index to an existing table. Returns error if the index name already exists.
func (*SchemaState) AddTable ¶
func (s *SchemaState) AddTable(name string, fields []Field, indexes []Index) error
AddTable adds a new table. Returns error if the table already exists. The fields and indexes slices are copied so that subsequent mutations to the state (e.g. DropField) do not corrupt the caller's original slice.
func (*SchemaState) AlterField ¶
func (s *SchemaState) AlterField(tableName string, newField Field) error
AlterField replaces a field (matched by name) in an existing table.
func (*SchemaState) DropField ¶
func (s *SchemaState) DropField(tableName, fieldName string) error
DropField removes a named field from an existing table.
func (*SchemaState) DropForeignKey ¶
func (s *SchemaState) DropForeignKey(tableName, constraintName string) error
DropForeignKey removes a named foreign key constraint from an existing table. Also removes the auto-generated FromFK index for the FK column, if present.
func (*SchemaState) DropIndex ¶
func (s *SchemaState) DropIndex(tableName, indexName string) error
DropIndex removes a named index from an existing table.
func (*SchemaState) DropTable ¶
func (s *SchemaState) DropTable(name string) error
DropTable removes a table. Returns error if the table does not exist.
func (*SchemaState) RenameField ¶
func (s *SchemaState) RenameField(tableName, oldName, newName string) error
RenameField renames a field within an existing table.
func (*SchemaState) RenameTable ¶
func (s *SchemaState) RenameTable(oldName, newName string) error
RenameTable renames a table. Returns error if old name does not exist or new name already exists.
func (*SchemaState) SetDefaults ¶
func (s *SchemaState) SetDefaults(defaults map[string]string)
SetDefaults updates the active schema defaults map on the state. Called by SetDefaults operations during migration traversal.
func (*SchemaState) SetTypeMappings ¶
func (s *SchemaState) SetTypeMappings(m map[string]string)
SetTypeMappings updates the active type mappings on the state. Called by SetTypeMappings operations during migration traversal.
type SetDefaults ¶
SetDefaults is a migration operation that records the active schema defaults (e.g. {"uuid": "uuid_generate_v4()"}) into the SchemaState so that subsequent operations can resolve symbolic default references at runtime. It emits no SQL — its sole purpose is to update the in-memory state.
func (*SetDefaults) Describe ¶
func (op *SetDefaults) Describe() string
Describe returns a human-readable description of this operation.
func (*SetDefaults) Down ¶
func (op *SetDefaults) Down(_ providers.Provider, _ *SchemaState, _ map[string]string, _ string) (string, error)
Down returns empty string — SetDefaults emits no SQL.
func (*SetDefaults) IsDestructive ¶
func (op *SetDefaults) IsDestructive() bool
IsDestructive returns false — setting defaults is not destructive.
func (*SetDefaults) Mutate ¶
func (op *SetDefaults) Mutate(state *SchemaState) error
Mutate updates the active schema defaults on the SchemaState.
func (*SetDefaults) TableName ¶
func (op *SetDefaults) TableName() string
TableName returns "" — SetDefaults does not target a specific table.
func (*SetDefaults) TypeName ¶
func (op *SetDefaults) TypeName() string
TypeName returns the operation type identifier.
type SetTypeMappings ¶
SetTypeMappings is a migration operation that records the active schema type mappings for the target database provider. It emits no SQL — its only effect is updating SchemaState.TypeMappings so that subsequent operations and the runner use the correct type overrides when generating SQL via ConvertFieldType.
func (*SetTypeMappings) Describe ¶
func (op *SetTypeMappings) Describe() string
Describe returns a human-readable description.
func (*SetTypeMappings) Down ¶
func (op *SetTypeMappings) Down(_ providers.Provider, _ *SchemaState, _ map[string]string, _ string) (string, error)
Down returns empty string — SetTypeMappings emits no SQL.
func (*SetTypeMappings) IsDestructive ¶
func (op *SetTypeMappings) IsDestructive() bool
IsDestructive returns false — SetTypeMappings is always non-destructive.
func (*SetTypeMappings) Mutate ¶
func (op *SetTypeMappings) Mutate(state *SchemaState) error
Mutate applies the type mappings to the schema state.
func (*SetTypeMappings) TableName ¶
func (op *SetTypeMappings) TableName() string
TableName returns "" — SetTypeMappings does not target a specific table.
func (*SetTypeMappings) TypeName ¶
func (op *SetTypeMappings) TypeName() string
TypeName returns the operation type identifier.
type TableState ¶
type TableState struct {
Name string `json:"name"`
Fields []Field `json:"fields"`
Indexes []Index `json:"indexes"`
ForeignKeys []ForeignKeyConstraint `json:"foreign_keys,omitempty"`
}
TableState holds the state of a single table.
type UpsertData ¶
type UpsertData struct {
// Table is the target table name.
Table string
// ConflictKeys lists the column names used to detect conflicts (primary key
// or unique constraint columns). Used in ON CONFLICT / MERGE ON / DELETE WHERE.
ConflictKeys []string
// Rows is the data to upsert. All rows must have the same keys. Values are
// formatted as SQL literals via FormatLiteral, supporting nil, string, bool,
// integer, float, and time.Time types.
Rows []map[string]any
// RowsFile is the relative path to a JSONL file containing row data.
// When set and Rows is empty, rows are loaded lazily at runtime from
// filepath.Join(migrationsDir, RowsFile).
RowsFile string
}
UpsertData is a migration operation that inserts or updates rows in a table. It is designed for seeding reference data (e.g. country codes, status enums, configuration rows) as part of a migration.
The operation generates database-appropriate upsert SQL via the active provider:
- PostgreSQL/AuroraDSQL: INSERT … ON CONFLICT … DO UPDATE SET
- MySQL/TiDB/StarRocks: INSERT … ON DUPLICATE KEY UPDATE
- SQLite/Turso: INSERT … ON CONFLICT … DO UPDATE SET
- SQL Server/Vertica: MERGE INTO … USING … WHEN MATCHED / NOT MATCHED
- Redshift: DELETE … ; INSERT …
- ClickHouse: INSERT (dedup via ReplacingMergeTree)
- YDB: UPSERT INTO …
Column order in the generated SQL is determined by sorting the keys of the first row alphabetically, so all rows must contain the same set of keys.
Rollback (Down) deletes each row by matching on ConflictKeys.
func (*UpsertData) Describe ¶
func (op *UpsertData) Describe() string
Describe returns a human-readable description of this operation.
func (*UpsertData) Down ¶
func (op *UpsertData) Down(p providers.Provider, _ *SchemaState, _ map[string]string, migrationsDir string) (string, error)
Down generates DELETE statements that remove each upserted row by matching on the ConflictKeys. Returns empty string when Rows or ConflictKeys is empty.
func (*UpsertData) IsDestructive ¶
func (op *UpsertData) IsDestructive() bool
IsDestructive returns false — upserting seed data is not considered destructive.
func (*UpsertData) Mutate ¶
func (op *UpsertData) Mutate(_ *SchemaState) error
Mutate is a no-op — UpsertData does not alter the schema state.
func (*UpsertData) TableName ¶
func (op *UpsertData) TableName() string
TableName returns the target table name.
func (*UpsertData) TypeName ¶
func (op *UpsertData) TypeName() string
TypeName returns the operation type identifier.
func (*UpsertData) Up ¶
func (op *UpsertData) Up(p providers.Provider, _ *SchemaState, defaults map[string]string, migrationsDir string) (string, error)
Up generates the upsert SQL by delegating to the provider's GenerateUpsert. Returns empty string when Rows is empty.
DefaultRef values in rows are resolved through the defaults map: if the key is present, the resolved SQL expression is emitted verbatim (not quoted); if not, the DefaultRef string itself is used as a raw SQL expression.