القائمة
Use when evolving a liteorm schema — AutoMigrate for additive changes, GenerateMigration/Diff for reviewable SQL, the migrate runner (Load/New/Up/Down), or WritePair.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when storing large or growing binary content (files, uploads, blobs) in SQLite as streamed io.ReaderAt/io.WriterAt instead of loading whole []byte — the orm.LOB field + liteorm.org/dialect/sqlite/lob.
Use when working with liteorm's declarative orm front-end — model structs and tags, AutoMigrate, the orm.Repo, associations (Load/Attach), hooks, or soft delete.
Use when liteorm code behaves unexpectedly, or proactively before writing it, to avoid the common gotchas around loading, soft delete, types, and dialect-gated operators.
Use when migrating a gorm codebase to liteorm — running models on gorm tags as-is, rewriting them to native orm tags, and adjusting for what differs.
Use when adding vector (sqlite-vec), full-text (FTS5), or hybrid RRF search to liteorm's SQLite backend.
Use when capturing, applying, inverting, or concatenating SQLite changesets (the SESSION extension) for audit logs, one-way replication, or undo — the liteorm.org/dialect/sqlite/changeset package. SQLite backend only.
| name | migrations |
| description | Use when evolving a liteorm schema — AutoMigrate for additive changes, GenerateMigration/Diff for reviewable SQL, the migrate runner (Load/New/Up/Down), or WritePair. |
liteorm separates the two cases. Additive changes auto-apply; destructive ones become reviewable SQL you run through the migrate runner. The runner (liteorm.org/migrate) executes SQL but never generates DDL; the orm package generates DDL but only auto-applies additions.
| Change | Tool |
|---|---|
| Add a table / column / index | orm.AutoMigrate[T] — applies immediately, never drops or alters types |
| Drop / retype / anything destructive | orm.GenerateMigration[T] — returns reviewable up/down SQL, executes nothing |
_ = orm.AutoMigrate[User](ctx, sess)
_ = orm.AutoMigrate[Order](ctx, sess, orm.WithForeignKeys()) // opt-in FK constraints
_ = orm.AutoMigrateAll(ctx, sess, User{}, Order{}, Item{}) // one-liner for a set, in order (no options)
Creates a missing table (plus its unique indexes and m2m junctions) or ADD COLUMNs for fields the model gained. Also syncs indexes additively: an index/unique tag added to an existing model's field is created on the next migrate (a removed tag is reviewable, never an auto DROP INDEX). Iterates the model, never the DB, so it can never drop.
Foreign keys are opt-in (off by default — relations ship as plain columns): orm.WithForeignKeys() emits a FOREIGN KEY for every belongs-to on a newly created table, or orm:"constraint:fk" opts in one relation. Migrate the referenced table first; adding a constraint to an existing table is reviewable-only.
ch, _ := orm.Diff[User](ctx, sess) // Changes{Added []*Field, Removed []ColumnMeta, Changed []ColumnChange}; ch.Empty()
up, down, _ := orm.GenerateMigration[User](ctx, sess)
// up/down are SQL strings — NOT executed. Added cols become ADD/DROP;
// removed cols become a commented "-- destructive" DROP; a type change becomes a
// commented "-- reviewable type change" ALTER (a rebuild note on SQLite).
ch.Changed reports columns whose type the model changed. Detection canonicalizes both sides before comparing, so cross-dialect spellings (BIGSERIAL/bigint, VARCHAR(255)/varchar, TINYINT(1)/tinyint) don't false-positive; an un-canonicalizable type reports no change (conservative — a missed change is a safe no-op, a false one churns migrations). Type changes are never auto-applied. Index introspection is the optional orm.IntrospectIndexes(ctx, sess, table).
You review the SQL, then either run it yourself or feed it into the runner via WritePair.
State lives in a single-row (version, dirty) ledger table (default schema_migrations), created dialect-aware. A failed step leaves the ledger dirty; the next run refuses until you Force.
import (
"embed"
"liteorm.org/migrate"
)
//go:embed migrations/*.sql
var migFS embed.FS
migs, _ := migrate.Load(migFS) // reads an fs.FS subtree
m := migrate.New(sess) // also migrate.WithTable("name")
n, err := m.Up(ctx, migs) // apply all pending, in version order
| Method | Does |
|---|---|
m.Up(ctx, migs) | Apply every pending migration (returns count). |
m.UpTo(ctx, migs, target) | Apply up to and including target. |
m.Down(ctx, migs) | Roll back the most recent step (errors if its down is empty). |
m.DownTo(ctx, migs, target) | Roll back everything above target. |
m.Status(ctx, migs) | []Status{Version, Name, Applied}. |
m.Version(ctx) | (version, dirty, err). |
m.Force(ctx, version) | Set version + clear dirty (recovery). |
migrate.Load auto-detects three on-disk formats so adopters keep history:
NNN_name.up.sql / NNN_name.down.sql-- +goose Up / -- +goose DownNNN_name.sql (up-only)migrate.WritePair writes a golang-migrate-style pair that Load reads back — so a generated diff drops straight into the runner an adopter already uses.
up, down, _ := orm.GenerateMigration[User](ctx, sess)
upPath, downPath, err := migrate.WritePair("migrations", 2, "add user fields", up, down)
// → migrations/000002_add_user_fields.up.sql and .down.sql
Version is zero-padded to six digits; the name is slugified. An empty up is an error; an empty down is written as an irreversibility comment so Down reports it as irreversible rather than silently succeeding.
GenerateMigration + the runner.Up/Down: fix the DB by hand, then Force to the correct version.Down errors instead of skipping it.