sqlite

GORM SQLite Driver

A GORM driver for SQLite-compatible databases, based on libsql-client-go. It is pure Go and needs no CGO.

go get codeberg.org/morelj/gorm-sqlite-libsql

The package is named sqlite, so an aliased import keeps call sites readable.

Quick Start

import (
  sqlite "codeberg.org/morelj/gorm-sqlite-libsql"
  "gorm.io/gorm"
)

db, err := gorm.Open(sqlite.Open("libsql://your-db-your-org.turso.io?authToken=<token>"), &gorm.Config{})

For full documentation, visit https://gorm.io.

Supported DSNs

libsql-client-go is a remote client: it speaks the hrana protocol over HTTP or WebSocket and does not embed a SQLite engine. Only these schemes open:

authToken, auth_token and jwt are accepted as query parameters. To pass options that have no DSN equivalent — WithProxy, WithSchemaDb, WithRequestHeaders — build a connector yourself and hand over the pool:

connector, err := libsql.NewConnector(url, libsql.WithAuthToken(token), libsql.WithProxy(proxy))
if err != nil {
  return err
}
db, err := gorm.Open(sqlite.New(sqlite.Config{Conn: sql.OpenDB(connector)}), &gorm.Config{})

Local databases are not supported

There is no local SQLite engine in this driver, so a file path or an in-memory DSN does not open:

sqlite.Open("gorm.db")                          // error: unsupported URL scheme
sqlite.Open(":memory:")                          // error: missing protocol scheme
sqlite.Open("file:x?mode=memory&cache=shared")   // error: no sqlite driver present

For a file: DSN, libsql-client-go delegates to a driver already registered with database/sql under the name sqlite or sqlite3. Importing one alongside this driver restores local support:

import (
  _ "modernc.org/sqlite"           // registers "sqlite", pure Go
  // or _ "github.com/mattn/go-sqlite3" // registers "sqlite3", requires CGO

  sqlite "codeberg.org/morelj/gorm-sqlite-libsql"
)

// file: DSNs now work; a bare path still needs the file: prefix
db, err := gorm.Open(sqlite.Open("file:gorm.db"), &gorm.Config{})

Error Translation

Set gorm.Config{TranslateError: true} to receive gorm.ErrDuplicatedKey and gorm.ErrForeignKeyViolated. hrana reports a failed statement as a message rather than a numeric result code, so constraint failures are classified from the text SQLite produces. A driver supplied through Config.DriverName or Config.Conn whose error type has a Code() int method is classified from that code instead.

Alternative Drivers

Testing

Unit tests need no database:

go test ./...

The tests that exercise the migrator and error translation against a live server skip unless GORM_LIBSQL_DSN names a scratch database — they empty its schema before each test:

GORM_LIBSQL_DSN=http://127.0.0.1:8080 go test ./...

AI Assistance

The port of this driver from go-sqlite3 to libsql-client-go was carried out with the help of an AI coding assistant (Claude Code). This covered swapping the underlying driver, rewriting error translation to classify constraint failures from the message hrana returns rather than from a numeric result code, and restructuring the tests that used to run against a local SQLite file.

The resulting code was validated by the test suite, including a run of the integration tests against a live hrana server. Treat it as you would any contribution: the upstream driver this is derived from carries its own history, and bugs introduced here are ours.