index.md

LiteORM documentation

LiteORM is a Go data-access library with two front-ends over one CGo-free core: an explicit, generics-first query builder and a declarative, convention-driven orm. Both run against the same backends, the same transaction, and the same normalized errors — so you use orm for CRUD and drop to query for a hot path on the same connection without changing libraries.

New here? Start with Getting started, and if you're unsure which front-end to reach for, read Query or ORM? — the one decision that shapes everything else. Coming from gorm? Map what you know in Coming from gorm. Coding with an AI assistant? Set it up with AI agents & skills so it writes correct LiteORM from the start.

Getting started

• Getting started — install, connect, and your first query and model.
• Connecting to a database — opening each backend, DSN shapes, :memory:, and config.
• Query or ORM? — what each front-end is and which to use for which job.
• Coming from gorm — the verb-for-verb map and what's intentionally different.
• Recipes — copy-paste solutions for common tasks; Cheat sheet — the whole API on one screen.

Querying — the query builder

• The query builder — the typed, generics-first builder in one page, with links into each task.
• Reading data · Joins & subqueries · Advanced SQL (CTEs, window functions, set operations, locking) · Writing data · Streaming & aggregates · Raw SQL.

Modeling — the orm front-end

• The orm front-end — declarative models, migrate, CRUD, and where to go deeper.
• Declaring models · CRUD with the Repo · Associations (N+1-safe eager loading) · Hooks · Scopes · Soft delete · Conventions.

Working with data

• Transactions — closure helpers, retry, savepoints, and query↔orm interop on one transaction.
• Errors — normalized sentinels that are the same on every backend.
• Field codecs — transform a field on read/write without changing its Go type.
• Context & session — the Session both *DB and a transaction satisfy, and context on every call.
• Statement logging · Observability — trace, meter, or audit every statement.

Schema & migrations

• Migrations — additive AutoMigrate, reviewable diffs, and the runner.
• Indexes & constraints · Composite keys · Code generation (typed columns, models from a live DB, SQL→Go, the sqlc plugin, the gorm porter).

SQLite superpowers

• Which SQLite feature? — a decision map for the pieces below.
• Search (vector / FTS5 / hybrid) · Large objects · At-rest encryption · Vault (compressed & encrypted databases) · Changesets.

Backends & dialects

• Postgres — LISTEN/NOTIFY and typed JSONB / array operators.
• Backends — opening each backend and the capability matrix; Dialects — placeholders, quoting, feature flags, quirks.

Tooling

• Studio — the embedded browser admin GUI with built-in AI, mounted as an http.Handler.
• AI agents & skills — set up your assistant with the shipped Agent Skills.

Going to production

• Performance · Security · Testing · Concurrency & locking · Deploying migrations.

Reference

• Configuration — the Open-time and DB-level options.
• Supported Go · Changelog · Cheat sheet.
• The complete, always-current API is on pkg.go.dev/liteorm.org — and per package: query, orm, migrate, gen, dialect/sqlite.

For AI agents

LiteORM ships first-class support for AI coding assistants — see AI agents & skills for the full setup. In short: if you're an assistant building with LiteORM, load the task recipes in skills/; if you're working inside this repository, read AGENTS.md.