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 Open(path string, 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 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 encryption recorder. 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 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 OpenConfig

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

OpenConfig opens SQLite from a full gosqlite.Config, for callers that need encryption, a custom VFS, or non-default pragmas/pool sizing. The returned liteorm.DB carries the SQLite dialect; pass the same config's advanced fields (e.g. Encryption) straight through to the driver.

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 gosqlite's default Adiantum cipher (a 32-byte key). Encryption refuses ":memory:" and is mutually exclusive with a custom VFS — see gosqlite's Config.Encryption. The recommended pragma preset still applies.

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).