메뉴
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.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
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.
Use when instrumenting liteorm with metrics, tracing, or audit around every executed statement — the Observer seam (liteorm.WithObserver + QueryEvent). Distinct from slog statement logging (the logging skill), which rides the same seam.
| name | large-objects |
| description | 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. |
Import liteorm.org/dialect/sqlite/lob. A large object is binary content too big to load whole — a file, an upload, a media blob — stored in SQLite and read/written incrementally at O(chunk) memory, never materialized as a []byte. SQLite-only and capability-gated: the helpers take a liteorm.Session opened by liteorm.org/dialect/sqlite and return lob.ErrUnsupportedBackend for any other dialect. The streaming engine is the sibling driver's gosqlite.org/blobstore; this package is the typed, model-bound front door over it.
The row stores only an 8-byte object id (an INTEGER column); the bytes live in a content sidecar and are addressed out-of-band. Importing the package registers the AutoMigrate provisioner, so a LOB field provisions its content store the same way a search index provisions its sidecar.
type File struct {
ID int64 `orm:"id,pk"`
Path string `orm:"path,unique"`
Content orm.LOB `lob:"chunk=1m;compress=better"` // both optional
}
orm.AutoMigrate[File](ctx, db) // creates `files` + the `files_content` object store
orm.LOB is an INTEGER column holding the content object's id. It loads with the row (8 bytes); the bytes never do. A zero LOB is unallocated — the object is created on the first write and its id is written back into the struct and the row.lob:"chunk=<size>" tunes the per-object chunk size (k/m/g suffix; default ~64 KiB, frozen per object at creation). Larger chunks suit big streamed files; smaller chunks waste less tail space for many small objects.lob:"compress=<level>" stores content compressed (fastest|fast|default|better|best; a bare compress means default). The mode is frozen per object at creation and reads are mode-agnostic, so raw and compressed objects coexist in one store. It fits write-once / streamed compressible content (files, logs, JSON); skip it for already-compressed payloads or hot random partial updates (a partial write of a compressed object read-modify-writes its whole chunk). Prefer a larger chunk when compressing, and it composes with at-rest encryption (content is compressed before the pages are encrypted).orm.WithLOBChunkSize("Content", n) / orm.WithLOBCompression("Content", orm.CompressionBest) (each overrides only its knob; an unknown field name, non-positive chunk, or bad compression level errors). Since chunk/compression are frozen per object at creation, an override is a default for new objects, not persisted — pass the flag consistently every launch, and AutoMigrate before the first lob.Open. The options are fixed at the store's first open per database for the process; a later AutoMigrate with different options is a no-op. Introspect via read-only orm.SchemaOf[T]().LOBFields (never mutate it).f := &File{Path: "/video.mp4"}
repo.Create(ctx, f) // Content unallocated until first write
w, _ := lob.Open(ctx, db, f, "Content") // io.WriterAt + io.Closer; allocates on first use
io.Copy(io.NewOffsetWriter(w, 0), src) // or w.WriteAt(p, off) at arbitrary offsets
w.Close() // f.Content is now Allocated()
r, _ := lob.Read(ctx, db, f, "Content") // io.ReaderAt + io.Closer
chunk, _ := io.ReadAll(io.NewSectionReader(r, 1<<20, 4096)) // read a 4 KiB range at 1 MiB
r.Close()
n, _ := lob.Size(ctx, db, f, "Content") // logical length in bytes (0 if never written)
lob.Truncate(ctx, db, f, "Content", 0) // grow (sparse) or shrink
lob.Drop(ctx, db, f, "Content") // free the content; resets the field to unallocated
WriteAt offsets may be written in any order; gaps are sparse (read back as zeros). Each WriteAt is durable on return.Read of a field never written returns lob.ErrNotAllocated (treat as empty). Size of it returns 0.lob.Open(ctx, db, f, "Content", lob.WithCompression(orm.CompressionBest)) sets one object's level (overrides the tag; raw + compressed coexist). lob.SetCompression(ctx, db, f, "Content", c) changes/converts an existing object (content preserved).lob.Stat(ctx, db, f, "Content") → lob.Info{Size, StoredBytes, UniqueBytes, SharedBytes, Ratio, ChunkSize, Compressed, Level}.lob.Clone(ctx, db, dst, src, "Content") — O(metadata) copy-on-write copy of a large object.lob.WriteFrom(ctx, db, row, "Content", r) — stream an io.Reader into the object (one txn); lob.WriteFromTx for the in-transaction variant.lob.NewVersion(…, lob.WithLabel("v1")), lob.ListVersions, lob.OpenVersion(…, n), lob.SetRetention(…, lob.Policy{KeepVersions: N}) / lob.Prune; default retention at allocate via lob.WithVersioning(lob.Policy{…}).lob:"dedup" (or orm.WithLOBDedup) → content-addressed block dedup for the store (store-wide, fixed at first open).lob.InTx(ctx, db, func(tx *lob.Tx) error { … }) runs ORM writes via tx.Session() and content via lob.OpenTx/lob.WriteFromTx/lob.DropTx on one transaction — they commit/roll back together. AutoMigrate first; pool > 1 conn (default).lob.Open write commits on its own pooled connection; use lob.InTx (above) when the row and content must be atomic. Default pattern otherwise: stream bytes, then commit metadata.lob.Drop when you hard-delete — typically from a BeforeDelete hook on the model. Soft-delete keeps the content (so Restore still has it); only hard-delete should Drop.Open best-effort-frees the object if the persist fails.liteorm.org/dialect/sqlite/lob fails AutoMigrate loudly (it names the missing import) rather than silently skipping the content store.dialect/sqlite session returns lob.ErrUnsupportedBackend.