sqlite

README

sqlite

SQLite driver module for rio, the zero-surprise Go ORM. Built on the pure-Go modernc.org/sqlite driver — no cgo.

Driver modules are deliberately thin: constructors, precise error translation and DSN hygiene. All SQL grammar lives in rio itself.

Install

go get github.com/go-rio/sqlite

Usage

import (
	"github.com/go-rio/rio"
	"github.com/go-rio/sqlite"
)

db, err := sqlite.Open("app.db")
if err != nil {
	// ...
}
defer db.Close()

users, err := rio.From[User]().Where("age > ?", 18).All(ctx, db)

Bring your own *sql.DB (and pool configuration) with New:

sqlDB, err := sql.Open("sqlite", dsn) // modernc.org/sqlite
db := sqlite.New(sqlDB)

Default pragmas

Open appends two pragmas to the DSN unless the DSN already sets the same pragma itself:

Pragma	Default	Why
foreign_keys	1	SQLite ships with foreign key enforcement off — constraints parse but never fire. Without this pragma, rio.ErrForeignKeyViolated could never happen on SQLite.
busy_timeout	5000	Concurrent writers wait up to five seconds for the database lock instead of failing immediately with SQLITE_BUSY.

Set either _pragma yourself to override a default:

db, err := sqlite.Open("app.db?_pragma=busy_timeout(10000)")

New never touches pragmas — configure them in the DSN of the pool you pass in.

Error translation

Unique and primary key violations come back as rio.ErrDuplicateKey, foreign key violations as rio.ErrForeignKeyViolated. The driver's own *sqlite.Error stays in the chain, so errors.As keeps working:

if err := rio.Insert(ctx, db, &user); errors.Is(err, rio.ErrDuplicateKey) {
	// email already taken
}

License

MIT

Documentation

Overview

Package sqlite connects rio, the zero-surprise Go ORM, to SQLite through the pure-Go modernc.org/sqlite driver — no cgo required.

Driver modules are deliberately thin. This package contains exactly three things, and nothing else:

• Constructors: Open (from a DSN) and New (bring your own *sql.DB), both returning a *rio.DB speaking the built-in rio.SQLite dialect.
• Precise error translation: SQLite constraint failures become rio.ErrDuplicateKey and rio.ErrForeignKeyViolated, with the driver error kept in the chain for errors.As.
• DSN hygiene: Open enables foreign key enforcement and a busy timeout unless the DSN sets those pragmas itself.

All SQL grammar lives in github.com/go-rio/rio; this package never implements a dialect.

Index

• func New(db *sql.DB, opts ...rio.Option) *rio.DB
• func Open(dsn string, opts ...rio.Option) (*rio.DB, error)

Functions

func New

func New(db *sql.DB, opts ...rio.Option) *rio.DB

New wraps an existing *sql.DB — bring your own connection pool — in a *rio.DB speaking the rio.SQLite dialect with this package's error translator installed. A rio.WithErrorTranslator among opts wins over the built-in translator.

New performs no DSN hygiene, because the pool already exists. In particular, foreign key enforcement is whatever the caller's DSN says — and SQLite's historical default is off, in which case rio.ErrForeignKeyViolated can never happen (see Open).

func Open

func Open(dsn string, opts ...rio.Option) (*rio.DB, error)

Open opens a SQLite database and returns a *rio.DB speaking the rio.SQLite dialect with this package's error translator installed.

Before handing the DSN to modernc.org/sqlite, Open appends the default pragmas described on defaultPragmas — foreign_keys(1) and busy_timeout(5000). A _pragma the DSN already sets is respected, never overridden.

Like database/sql itself, Open validates nothing eagerly: a bad path or DSN surfaces on first use (or on an explicit Ping).