sqlite

glebarez/sqlite is a drop-in GORM dialect for SQLite that swaps the standard cgo-based driver (mattn/go-sqlite3) for a pure-Go SQLite implementation built on modernc.org/sqlite and glebarez/go-sqlite. Because there’s no C compiler in the build path, projects using it can compile with plain go build, run inside minimal Alpine containers, and deploy on platforms like Google Cloud Platform that don’t allow gcc to execute — all without changing application code beyond the import path.

The driver deliberately tracks go-gorm/sqlite upstream, porting behavior fixes so migrations and DDL parsing stay consistent between the cgo and pure-Go drivers. It layers in SQLite-specific pieces GORM needs — INSERT/LIMIT/FOR clause builders, RETURNING-clause support on SQLite 3.35+, identifier quoting, savepoints, and constraint-error translation (unique, primary key, foreign key, check) into GORM’s typed error values — while defaulting its registered driver name to sqlite rather than upstream’s sqlite3.

What You Get

• A gorm.Dialector implementation (sqlite.Open(dsn) / sqlite.New(config)) that’s a drop-in swap for the standard GORM SQLite driver
• No cgo requirement — builds with plain go build/go test, no C toolchain, works in scratch/Alpine containers and on cgo-restricted platforms like GCP
• Constraint-error translation that maps SQLite’s unique/primary-key/foreign-key/check violations to GORM’s typed errors (ErrDuplicatedKey, ErrForeignKeyViolated, ErrCheckConstraintViolated)
• RETURNING-clause support automatically enabled on SQLite 3.35+, with clause builders for INSERT, LIMIT/OFFSET, and locking no-ops tailored to SQLite semantics
• Foreign-key enforcement toggled via a _pragma=foreign_keys(1) DSN parameter, matching SQLite’s opt-in FK behavior
• In-memory database support via the standard :memory: DSN for tests and ephemeral state

Common Use Cases

• Building Go services that embed SQLite for local/edge storage without needing a C compiler in CI or Docker build images
• Deploying GORM-based applications to GCP or other environments where gcc execution is restricted or unavailable
• Running fast, hermetic tests against an in-memory SQLite database inside GORM-based test suites
• Cross-compiling Go binaries for multiple OS/architecture targets without per-target C toolchains
• Migrating an existing GORM + mattn/go-sqlite3 codebase to a pure-Go build with minimal code changes

Under The Hood

Architecture The package implements GORM’s Dialector and Migrator interfaces as a thin adaptation layer: sqlite.go defines Dialector.Initialize to open a database/sql connection against the pure-Go driver, detect the live SQLite version, and conditionally register RETURNING-aware callbacks for 3.35+; ClauseBuilders() supplies SQLite-specific SQL fragments for INSERT/LIMIT/FOR; and Migrator (in migrator.go, wrapping GORM’s generic migrator.Migrator) handles schema introspection and DDL by delegating to ddlmod.go’s CREATE TABLE statement parser to recover column definitions SQLite doesn’t expose directly through PRAGMA table_info. Errors surface through Translate, which type-switches on *gosqlite.Error and maps SQLite extended result codes to GORM’s sentinel errors, keeping the abstraction boundary at the dialect layer rather than leaking driver-specific errors to callers.

Tech Stack Go module targeting Go 1.18+, depending on gorm.io/gorm for the ORM contract, github.com/glebarez/go-sqlite as the pure-Go database/sql driver, and modernc.org/sqlite (plus its modernc.org/libc/mathutil/memory support packages) as the underlying C-to-Go transpiled SQLite engine — the same engine used to detect extended result codes for error translation. No build tooling beyond the Go toolchain; no external services.

Code Quality The repo carries a meaningful test suite for a driver of this size — ddlmod_test.go, migrator_test.go, sqlite_error_translator_test.go, sqlite_test.go, and generated_test.go — covering DDL parsing edge cases, migrator behavior, and error-code translation, and CI additionally runs the full ~12k-test GORM upstream test suite against the driver across Linux/Windows/macOS and multiple Go versions (per the README’s CI badges), which is unusually thorough validation for a dialect adapter. Naming and error handling follow Go and GORM conventions (typed sentinel errors, explicit type switches); no linter config beyond standard go vet-level tooling is present in the repo root.

API Design The public surface is minimal by design — Open(dsn) and New(config) — matching the calling convention of every other GORM dialect, so switching from the cgo driver is a single import change with no application-code rewrite. Foreign-key enforcement and other SQLite pragmas are configured through DSN query parameters rather than a bespoke options struct, keeping the driver’s own API surface small and pushing configuration into a syntax GORM users already recognize from other dialects.