SQLite driver for GORM

Pure-Go (no CGO) SQLite driver for GORM, powered by modernc.org/sqlite.

Drop-in replacement for go-gorm/sqlite (the official CGO-based driver).

Features

• Pure Go (no C compiler or external libraries required); cross-compiles to any Go-supported platform
• Compatible with the GORM test suite (tested on Linux, macOS, and Windows)
• JSON1, Math functions, FTS5, R-Tree, and Geopoly enabled by default

Install

go get github.com/libtnb/sqlite

Usage

import (
	"github.com/libtnb/sqlite"
	"gorm.io/gorm"
)

db, err := gorm.Open(sqlite.Open("sqlite.db"), &gorm.Config{})

In-memory database

db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})

DSN Parameters

Parameters are appended to the DSN as a query string:

dsn := "sqlite.db?_txlock=immediate&_pragma=journal_mode(WAL)&_pragma=foreign_keys(1)"
db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{})

Driver parameters

Parameter	Example	Description
_pragma	_pragma=journal_mode(WAL)	Execute a single PRAGMA statement on each new connection; can be specified multiple times.
_txlock	_txlock=immediate	Transaction locking mode: deferred (default), immediate, or exclusive.
_time_format	_time_format=sqlite	How time.Time is serialized to TEXT: sqlite (default, YYYY-MM-DD HH:MM:SS.SSS[+-]HH:MM) or datetime (YYYY-MM-DD HH:MM:SS).
_time_integer_format	_time_integer_format=unix	Store time.Time as INTEGER instead of TEXT: unix, unix_milli, unix_micro, or unix_nano. Overrides _time_format.
_timezone	_timezone=UTC	Timezone applied when reading and writing time values (parsed by time.LoadLocation).
_dqs	_dqs=0	Disable SQLite's double-quoted string literal quirk.
_defensive	_defensive=1	Enable SQLite's defensive mode.

mattn/go-sqlite3 compatible parameters

Shorthand keys for DSNs carried over from go-gorm/sqlite; invalid values fail the connection.

Parameter	Alias	Sets
_busy_timeout	_timeout	PRAGMA busy_timeout in milliseconds (default 5000)
_foreign_keys	_fk	PRAGMA foreign_keys
_journal_mode	_journal	PRAGMA journal_mode
_synchronous	_sync	PRAGMA synchronous
_auto_vacuum	_vacuum	PRAGMA auto_vacuum
_query_only		PRAGMA query_only

SQLite URI parameters

These are interpreted by SQLite itself, not the driver. Available when the DSN starts with file: (the driver opens connections with SQLITE_OPEN_URI).

Parameter	Example	Description
mode	mode=ro	Open mode: ro, rw, rwc (default), or memory.
cache	cache=shared	Cache mode: shared or private (default). See shared cache.
immutable	immutable=1	Treat the database as read-only and unchanging; enables optimizations for read-only media.
vfs	vfs=unix-excl	Use a specific VFS.

Common pragmas

Pragma	Recommended	Description
journal_mode(WAL)	Yes	Enable WAL mode to improve concurrent read performance.
busy_timeout(N)	Optional	Wait up to N milliseconds on SQLITE_BUSY. Defaults to 5s; override here or with _busy_timeout=N.
synchronous(NORMAL)	With WAL	Reduce fsync calls in WAL mode with minimal durability risk. See synchronous.
cache_size(-64000)	Optional	Set page cache size in KiB (negative value) or pages (positive value). Defaults to -2000 (2 MiB).
foreign_keys(1)	If using FKs	Enable foreign key constraint enforcement (disabled by default in SQLite).
secure_delete(1)	If sensitive data	Overwrite deleted content with zeros instead of leaving fragments in unused pages. Small I/O overhead.
auto_vacuum(FULL)	Long-lived DB	Reclaim space automatically: NONE (default), FULL, or INCREMENTAL. Must be set before any tables exist.
case_sensitive_like(1)	Optional	Make the LIKE operator case-sensitive (default is case-insensitive for ASCII).
recursive_triggers(1)	If using triggers	Allow triggers to fire recursively.

Warning

SQLite only allows one writer at a time, so concurrent writes will inevitably encounter SQLITE_BUSY (details). This cannot be fully avoided, but can be mitigated:

1. Tune busy_timeout to control how long writers wait before failing (5s by default)
2. Limit the connection pool to a single connection to reduce lock contention
3. Enable WAL mode to allow concurrent reads while writing

dsn := "sqlite.db?_txlock=immediate&_pragma=journal_mode(WAL)"
db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{})

sqlDB, _ := db.DB()
sqlDB.SetMaxOpenConns(1)
sqlDB.SetMaxIdleConns(1)

Note

This serializes all database access (reads and writes). If you need concurrent reads, consider using WAL mode with a separate read-only connection pool instead. This approach does not work with :memory: databases (details).

Process-wide settings

The driver turns on these modernc.org/sqlite switches when imported; call them with false before opening a database to opt out.

• StrictPragmas: reject a _pragma value holding more than one SQL statement.
• OFDLocking (Linux only): keep SQLite's file locks when the process closes another descriptor of the database file. MODERNC_SQLITE_OFD_LOCK=0 also disables it.
• Fdatasync (not on macOS and Windows): commit with fdatasync(2) instead of fsync(2).

Testing

Tests run on Linux, macOS, and Windows with the latest two Go releases. The full GORM test suite (12k+ cases) is included.

Credits

• glebarez/sqlite
• modernc.org/sqlite
• mattn/go-sqlite3
• gorm.io/gorm