sqlite

Documentation

Overview

Package sqlite is liteorm's SQLite backend. It wraps the sibling pure-Go driver gosqlite.org (it does NOT reimplement SQLite) and adapts its database/sql surface to liteorm's core contracts: Querier, Rows, Result, Beginner, Tx (with savepoint-nested Begin), the LastInsertIder capability, and SQLite error normalization via the driver's extended result codes.

Index

• func Conn(sess liteorm.Session) (*gosqlite.DB, bool)
• func DropTriggers(ctx context.Context, sess liteorm.Session, names ...string) error
• func Open(path string, opts ...liteorm.Option) (*liteorm.DB, error)
• func OpenCompressed(path string, opts ...liteorm.Option) (*liteorm.DB, error)
• func OpenCompressedConfig(cfg gosqlite.Config, copts compress.Options, opts ...liteorm.Option) (*liteorm.DB, error)
• func OpenConfig(cfg gosqlite.Config, opts ...liteorm.Option) (*liteorm.DB, error)
• func OpenEncrypted(path string, key []byte, opts ...liteorm.Option) (*liteorm.DB, error)
• func OpenEncryptedConfig(cfg gosqlite.Config, copts crypto.Options, opts ...liteorm.Option) (*liteorm.DB, error)
• func Pin(ctx context.Context, sess liteorm.Session) (bound *liteorm.DB, gc *gosqlite.Conn, release func() error, err error)
• func Rowid() query.Field
• func RowidCol() query.Column[int64]
• func WhereRegex(column, pattern string) (sql string, args []any)

Functions

func Conn

func Conn(sess liteorm.Session) (*gosqlite.DB, bool)

Conn returns the underlying *gosqlite.DB for a liteorm.Session opened by this package, giving the SQLite-specific subpackages (search, changeset) access to gosqlite's typed surface (vec, FTS5, sessions) and the blobstore engine. The second result is false for any other backend or for a transaction handle (those features operate at the database level). It never leaks a gosqlite type into the core: this lives in the SQLite backend, which already depends on it.

func DropTriggers

func DropTriggers(ctx context.Context, sess liteorm.Session, names ...string) error

DropTriggers issues DROP TRIGGER IF EXISTS for each name, in order. It is idempotent across runs — a trigger that doesn't exist is a silent no-op — so it suits a migrate/startup path that cleans up legacy trigger names left behind by an earlier schema generation (e.g. a renamed FTS5 external-content trigger). Each name is quoted as an identifier by the dialect, which is injection-safe by construction; an empty name is rejected and the call short-circuits.

It is SQLite-only: trigger DDL is dialect-specific (PostgreSQL/MySQL trigger management differs), so a normalized cross-dialect form is intentionally out of scope. This is a schema utility, not a recorded migration — for reviewable, ledgered up/down changes use liteorm.org/migrate instead.

func Open

func Open(path string, opts ...liteorm.Option) (*liteorm.DB, error)

Open opens a SQLite database at path via gosqlite.org with the production pragma preset (WAL + busy_timeout=5s + foreign_keys=on) and returns a liteorm.DB on the SQLite dialect.

func OpenCompressed

func OpenCompressed(path string, opts ...liteorm.Option) (*liteorm.DB, error)

OpenCompressed opens a SQLite database stored compressed on disk at path, via gosqlite.org/vfs/compress, using the default level. Use it exactly like a database from Open: orm, query, and migrations all work above it.

SNAPSHOT MODEL — read this. The compressed file is inflated into a full, plaintext working copy (under the OS temp dir) for the lifetime of the handle, and rewritten compressed only on Close. Two consequences follow:

• Durability is per-SESSION, not per-transaction. A crash while the database is open reverts the on-disk file to its previous Close — no corruption, but in-session changes are lost. This is unlike every other Open here.
• The working copy is plaintext, so this is NOT a substitute for at-rest encryption (OpenEncrypted), and the two cannot be composed live.

It fits archival, distribution, shipping an embedded database, and open-modify-close tooling over compressible data — not a database that must stay open continuously or survive a crash mid-session. Keep one open handle per compressed file. For an offline transform without a session, call gosqlite.org/vfs/compress's Pack / Unpack directly.

func OpenCompressedConfig

func OpenCompressedConfig(cfg gosqlite.Config, copts compress.Options, opts ...liteorm.Option) (*liteorm.DB, error)

OpenCompressedConfig opens a compressed-at-rest SQLite database from a full gosqlite.Config plus compress.Options, for callers that need a non-default level (compress.CompressionBest, …), a working-copy TempDir, or custom pragmas/pool sizing. cfg.VFS must be empty and cfg.Path must be on disk (in-memory is rejected). See OpenCompressed for the snapshot-model semantics: durability is per-session and the working copy is plaintext.

func OpenConfig

func OpenConfig(cfg gosqlite.Config, opts ...liteorm.Option) (*liteorm.DB, error)

OpenConfig opens SQLite from a full gosqlite.Config, for callers that need a custom VFS or non-default pragmas/pool sizing. The returned liteorm.DB carries the SQLite dialect. For at-rest encryption use OpenEncrypted or OpenEncryptedConfig, which register the cipher VFS for you.

func OpenEncrypted

func OpenEncrypted(path string, key []byte, opts ...liteorm.Option) (*liteorm.DB, error)

OpenEncrypted opens an at-rest-encrypted SQLite database at path using the default Adiantum cipher (a 32-byte key). Encryption refuses ":memory:" (there is nothing to encrypt at rest). The recommended pragma preset still applies. For AES-XTS, a non-default page size, or a passphrase-derived key, use OpenEncryptedConfig.

func OpenEncryptedConfig

func OpenEncryptedConfig(cfg gosqlite.Config, copts crypto.Options, opts ...liteorm.Option) (*liteorm.DB, error)

OpenEncryptedConfig opens an at-rest-encrypted SQLite database from a full gosqlite.Config plus crypto.Options, for callers that need AES-XTS (crypto.AESXTS, a 64-byte key), a non-default PageSize, a passphrase-derived key (crypto.DeriveKey), or custom pragmas/pool sizing. The cipher is a VFS that gosqlite.org/vfs/crypto registers and tears down on Close, so cfg.VFS must be empty. Encryption refuses an in-memory database.

The page-level cipher format is unchanged, so a database encrypted by an earlier liteorm release opens with the same key. When reopening an existing database created with a non-default page size, set crypto.Options.PageSize to match its PRAGMA page_size (it defaults to 4096); a mismatch fails to decrypt.

func Pin

func Pin(ctx context.Context, sess liteorm.Session) (bound *liteorm.DB, gc *gosqlite.Conn, release func() error, err error)

Pin acquires a single dedicated connection from sess's pool and returns it both as a liteorm.Session (so liteorm repos and raw exec run on exactly this physical connection) and as the gosqlite *Conn — the receiver for connection- scoped features such as the SESSION/changeset extension. Call release when done to return the connection to the pool; until then the *Conn stays valid. sess must be a *liteorm.DB opened by this package (not a transaction).

func Rowid

func Rowid() query.Field

Rowid is the "rowid" column as a projection Field, for selecting the implicit key alongside model columns in a query.Into projection without a raw fragment:

query.Into[Item, reindexRow](ctx, b, sqlite.Rowid(), query.Name("title"))

It is the typed, dialect-quoted counterpart of query.Expr("rowid").

func RowidCol

func RowidCol() query.Column[int64]

RowidCol is a typed column token for SQLite's implicit "rowid" — the 64-bit row key every ordinary table has (also reachable as "oid"/"_rowid_"). It is an Unvalidated column, so it passes the model-schema validation that would otherwise reject "rowid" as an undeclared field. Use it anywhere a Column[int64] is accepted — Filter, Order, Pluck:

query.Select[Item](db).Order(query.Asc(sqlite.RowidCol()))
query.Pluck[Item, int64](ctx, b, sqlite.RowidCol())
query.Select[Item](db).Filter(sqlite.RowidCol().Gt(lastSeen))

On a table whose primary key is an INTEGER PRIMARY KEY, "rowid" is an alias of that PK column — so a Rowid projection reports the PK column's name, and you'd scan it through the PK field. Rowid is most useful on tables whose key is not an integer PK (a string-keyed or WITHOUT ROWID-adjacent model), where it is a distinct implicit column.

func WhereRegex

func WhereRegex(column, pattern string) (sql string, args []any)

WhereRegex returns a query-builder WHERE fragment (and its bind args) that matches column against an RE2 regular expression. When pattern is left-anchored it prepends a GLOB prefix so SQLite can range-scan an index on column and run REGEXP only on the survivors; an unanchored pattern falls back to a plain REGEXP filter. Pass the result straight to the query builder:

frag, args := sqlite.WhereRegex("title", `^Intro to .* with Go$`)
rows, err := query.Select[Doc](db).Where(frag, args...).All(ctx)

The REGEXP operator must be registered on the connection — blank-import gosqlite.org/ext/regexp/auto (gosqlite registers it globally, so it then works through liteorm with no further wiring).