Documentation
¶
Overview ¶
Package sqlitedriver adapts mattn/go-sqlite3 and sqlite-vec to momo.
Requirements ¶
The package needs cgo and a C toolchain, and it is not built for Windows, where the sqlite-vec C sources cannot be compiled. In a build without cgo, or for Windows, Open reports momo.ErrUnsupported. The cgo-free alternative is package sqlitepure (modernc.org/sqlite), which has no vector support.
Process-wide effects ¶
Importing the package has no side effect. The first Open registers the database/sql driver "momo-sqlite3" and calls sqlite_vec.Auto, which installs sqlite-vec through sqlite3_auto_extension. That registration is process-wide: every SQLite connection opened afterwards by any package in the process that links the same SQLite library gets the vec_* functions, not only the connections momo opens.
Hardening ¶
Every connection momo opens verifies that load_extension is disabled and that SQLite is at least 3.35.0. For defence in depth, build the program with -tags sqlite_omit_load_extension, which removes extension loading from the SQLite library altogether.
Defaults ¶
Config is optional. Its zero values select a 5s busy timeout, synchronous NORMAL, immediate transactions and one open connection (the single-writer guidance for SQLite). The adapter also sets WAL journalling and foreign keys on every connection; a DSN cannot switch those off.
Index ¶
Constants ¶
const SQLiteVecVersion = "v0.1.6"
SQLiteVecVersion is the sqlite-vec release this module is built and tested against, as vec_version() reports it. Open accepts that release and any later patch release of the same minor version (v0.1.x at or above this), so a go.mod that resolves the bindings to a newer patch release keeps working; another minor or major version fails at Open, because the set of distance functions may differ. The test TestSQLiteVecLoaded compares vec_version() with this constant exactly, so a change of the bindings version in go.mod is noticed. Vector columns are BLOB columns with a length CHECK; see momo.SQLiteVectorType and momo.SQLiteBitsType.
Variables ¶
This section is empty.
Functions ¶
func ClassifyError ¶
ClassifyError maps a mattn sqlite3.Error to *momo.Error. Other errors, and errors that are already *momo.Error, are returned unchanged. SQLite messages name tables and columns and never carry row values, so the message is safe to render; the sqlite3.Error stays reachable through errors.As.
func Open ¶
Open opens a SQLite database with mattn/go-sqlite3 and sqlite-vec. The caller owns the returned *sql.DB. Every new connection verifies sqlite_version() >= 3.35.0 and that load_extension is disabled; Open pings the database so a refused connection is reported here.
dsn is a file path or a "file:" URI. The query string may carry only the parameters on allowedDSNKeys, each given once; a repeated parameter, a _txlock other than immediate, deferred or exclusive, a _busy_timeout or _timeout that is not a non-negative integer, a _cache_size that is not an integer (a negative one is a size in KiB) and a _loc that is neither "auto" nor a time zone name are refused with momo.ErrValidation. The busy timeout and the transaction lock in it override cfg; foreign keys, WAL and synchronous always come from cfg and the adapter. The mode and cache parameters are SQLite URI parameters, which SQLite sees only for a "file:" DSN, so any other DSN carrying them is refused. mode=ro cannot open a database that is not in WAL mode yet, because the adapter sets journal_mode=WAL on every connection and a read-only connection cannot change it: create the database read-write first. An in-memory database with MaxOpenConns above 1 needs cache=shared, and then a statement can fail with SQLITE_LOCKED, which ClassifyError reports as momo.ErrBusy.
Types ¶
type Config ¶
type Config = sqliteconf.Config
Config holds the recommended SQLite settings. Zero values select the defaults: BusyTimeout 5s, Synchronous "NORMAL", TxLock "immediate" and MaxOpenConns 1 (the single-writer guidance; a goroutine that holds a transaction or pinned connection and then uses the pool deadlocks with one connection). It is the same type as sqlitepure.Config; see internal/sqliteconf for the field list.
Source Files