sqlite

README

vormia-go-driver-sqlite

Pure-Go SQLite driver for the Vormia Go framework. Thin wrapper around database/sql and modernc.org/sqlite that validates the shared Database contract with zero infrastructure — no Docker, no server, no C compiler.

Version: v1.1.0 — verified ready for vormia-go v1.2.x db.Wipe / seed.Run (catalog query, transactional DROP, :memory: pool pin). No API changes from v1.0.0.

Install

go get github.com/vormialabs/vormia-go-driver-sqlite@v1.1.0

Quick start

package main

import (
	"context"
	"fmt"
	"log"

	sqlite "github.com/vormialabs/vormia-go-driver-sqlite"
)

func main() {
	db, err := sqlite.Open(sqlite.Config{
		Path:        ":memory:",
		ForeignKeys: true,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	ctx := context.Background()

	if _, err := db.ExecContext(ctx,
		`CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL)`); err != nil {
		log.Fatal(err)
	}
	if _, err := db.ExecContext(ctx,
		`INSERT INTO users (name) VALUES (?)`, "Ada"); err != nil {
		log.Fatal(err)
	}

	rows, err := db.QueryContext(ctx, `SELECT name FROM users WHERE name = ?`, "Ada")
	if err != nil {
		log.Fatal(err)
	}
	defer rows.Close()

	for rows.Next() {
		var name string
		if err := rows.Scan(&name); err != nil {
			log.Fatal(err)
		}
		fmt.Println(name)
	}
}

Config

Field	Purpose
Path	File path, or :memory: for an in-memory database (default :memory:)
ForeignKeys	Enable FK enforcement (OFF by default in SQLite)
BusyTimeoutMS	Milliseconds to wait on a locked DB before erroring
WAL	Enable write-ahead logging for better file-DB concurrency

For file databases with concurrent writes, set WAL: true and a BusyTimeoutMS (e.g. 5000).

Rebind

Apps write queries with ? placeholders. Call db.Rebind(q) before executing. SQLite's Rebind is the identity function; Postgres will convert ? → $1, $2, ….

q := db.Rebind(`SELECT * FROM users WHERE id = ?`)
rows, err := db.QueryContext(ctx, q, userID)

Wipe / seed readiness

vormia-go's db.Wipe and seed.Run call only the existing Database contract (QueryContext, ExecContext, BeginTx). This driver needs no wipe-specific helpers:

• Catalog enumeration uses a plain SELECT against sqlite_master.
• SQLite supports transactional DDL, so wipe wraps drops in BeginTx / Commit.
• Multi-step wipe/seed sequences on :memory: share the single pinned connection (see gotcha 1).

Gotchas

1. :memory: + connection pool = data disappears. Each connection gets its own in-memory DB. Open pins :memory: to one connection via SetMaxOpenConns(1).
2. Foreign keys are OFF by default. SQLite ignores REFERENCES unless you set ForeignKeys: true.
3. File DB concurrency. SQLite serializes writes. Use WAL: true and BusyTimeoutMS for real workloads.
4. Pragma DSN syntax is driver-specific. The _pragma=... form is modernc.org/sqlite's. Switching to mattn/go-sqlite3 would require different DSN syntax.

Docs worth knowing

• database/sql — DB, Tx, Rows, context methods
• modernc.org/sqlite — pure-Go driver, DSN and pragma syntax
• SQLite foreign keys — FK behavior and pragmas

License

MIT

Documentation

Index

• type Config
• type DB
  • func Open(cfg Config) (*DB, error)
  • func (d *DB) Rebind(query string) string

Types

type Config

type Config struct {
	// Path is the file path, or ":memory:" for an in-memory database.
	Path string
	// ForeignKeys enables FK enforcement (OFF by default in SQLite).
	ForeignKeys bool
	// BusyTimeoutMS is how long to wait on a locked DB before erroring.
	BusyTimeoutMS int
	// WAL enables write-ahead logging (better concurrency for file DBs).
	WAL bool
}

Config describes how to open a SQLite database.

type DB

type DB struct {
	*sql.DB
}

DB wraps *sql.DB. By embedding it, all standard methods (QueryContext, ExecContext, BeginTx, PingContext, Close, ...) are promoted and satisfy the framework's Database contract directly.

func Open

func Open(cfg Config) (*DB, error)

Open builds the DSN, opens the pool, and verifies connectivity.

func (*DB) Rebind

func (d *DB) Rebind(query string) string

Rebind returns the query unchanged: SQLite uses ? placeholders natively. (Postgres's driver will implement a real ? -> $N conversion here.)