sqlite

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package sqlite opens SQLite databases for the SQL layer: OpenDB returns a configured *sql.DB over the pure-Go modernc.org/sqlite driver, and Dialect describes the engine to platform/sql/dialect.

Role

platform layer: the SQLite driver under platform/sql. It opens the pool of one SQLite database with the connection settings every store relies on, and describes the engine as a dialect.Dialect. It knows nothing of stores, migrations or keyrings: the caller pings the pool, migrates it and wraps it in a store. Among this module's packages it imports only platform/sql/dialect.

Inputs

  • A database path, or Memory for a private in-memory database, and Options, the busy timeout.
  • Driving: the store opener, which opens the composite store over the pool that OpenDB returns, and, from STO-08 (issue 996), the module SQL test harness, which opens its databases through OpenDB.

Outputs

  • OpenDB: a pool over the "sqlite" driver that modernc.org/sqlite registers, not yet connected, or ErrPathRequired for an empty path.
  • DSN: the connection string OpenDB opens, with its pragmas and IMMEDIATE transactions.
  • Dialect, SQLite's dialect.Dialect, and IsUniqueViolation, the unique-violation test it carries.
  • Options, Memory and ErrPathRequired.

Invariants

  • The driver is modernc.org/sqlite, which is pure Go, so the server builds without CGO on every platform (decision 0004).
  • Transactions begin IMMEDIATE, taking the write lock up front. With WAL and a busy timeout, 10s unless Options sets one, this serialises writers without deadlocks, and readers keep reading while one writes. Every connection also enforces foreign keys and runs with synchronous NORMAL.
  • Memory opens a private in-memory database on one connection, which the pool never closes for age or idleness, so the database lives as long as the pool: each connection to ":memory:" sees its own empty database, and a second connection would find none of the tables.
  • Dialect.Columns lists a table's columns through the table-valued form of PRAGMA table_info, so the table name binds as a parameter.
  • IsUniqueViolation reports SQLite's unique and primary-key constraint failures only, which the SQL store turns into kernel.ErrConflict; every other constraint failure stays a driver error.
  • Error texts start with "sqlite:" and stay byte-identical, because operators read them behind the store opener's "open store: ".

References

  • Decision 0004: docs/research/decisions/0004-storage-sql-metadata-and-blobs.md ("Metadata": SQLite through modernc.org/sqlite, CGO-free, with WAL and one writer).
  • Decision 0044: docs/research/decisions/0044-modular-monolith-migration.md ("Persistence": the platform drivers open the engines, and app/adapters/sql/sqlite opens the composite store over them; "Names the migration introduces").
  • Target layout: docs/research/architecture-options/5-modular-monolith.md, lines 132 and 133 (platform/sql/sqlite, the driver open, pragmas and IMMEDIATE transactions, and platform/sql/postgres), line 584 (open and driver settings) and line 1043 (the mapping row).
  • Plan: docs/implementation/plan.md#p2-stores, task 2, and #p9d-modular-monolith-migration, epic STO (https://github.com/weaveplatform/artifactweave/issues/939).
  • https://github.com/weaveplatform/artifactweave/issues/995

Status

Implemented P2: the SQLite store's open with WAL, the busy timeout and IMMEDIATE transactions, the in-memory database on one connection and the unique-violation test (pull request 3). Moved here in P9d: the migrations left for each module's stream, and Dialect gained Columns (issue 994); the driver left the composite store's open for this package, with OpenDB and its Options (issue 995).

Testing

  • TestUnitOpenDBRefusesAnEmptyPath, TestUnitDSNCarriesThePragmas, TestAccOpenDBKeepsMemoryOnOneConnection, TestAccOpenDBAppliesThePragmas, TestAccOpenDBBeginsImmediate, TestAccIsUniqueViolation and TestAccIsUniqueViolationReadsTheConstraintCodes run the driver alone, in memory and in temporary files.
  • The composite store's suites on SQLite open every database through OpenDB: the metadata store's contract (TestAccContractFile and TestAccContractMemory), TestAccKeyRotation, TestAccOpenErrors, TestAccMigrationsUpDownUp, TestAccSchemaGolden and the store opener's TestAccOpenStoreErrors.

Index

Constants

View Source
const Memory = ":memory:"

Memory is the path that opens a private in-memory database, which lives as long as the pool that OpenDB returns for it.

Variables

View Source
var Dialect = dialect.Dialect{
	Name: "sqlite",

	Columns:           "SELECT name FROM pragma_table_info(?)",
	IsUniqueViolation: IsUniqueViolation,
}

Dialect is SQLite's dialect.Dialect, with IsUniqueViolation: "?" placeholders, and no row-lock suffix, because IMMEDIATE transactions already serialise writers.

View Source
var ErrPathRequired = errors.New("sqlite: path is required")

ErrPathRequired is returned by OpenDB for an empty path.

Functions

func DSN

func DSN(path string, o Options) string

DSN returns the modernc connection string that OpenDB opens for path: the busy timeout, 10s unless o sets one, WAL journaling, foreign keys, synchronous NORMAL and IMMEDIATE transactions.

func IsUniqueViolation

func IsUniqueViolation(err error) bool

IsUniqueViolation reports whether err is, or wraps, a SQLite unique or primary-key constraint failure, which the SQL store turns into kernel.ErrConflict. Any other error, another constraint failure included, reports false.

func OpenDB

func OpenDB(path string, o Options) (*sql.DB, error)

OpenDB returns a pool over the SQLite database at path, through the "sqlite" driver that modernc.org/sqlite registers, with the settings of DSN. It does not connect: the pool's first connection creates a missing database file, and a path that cannot be opened fails there. Memory opens a private in-memory database on one connection that the pool never closes for age or idleness, because each connection to ":memory:" sees its own empty database. OpenDB returns ErrPathRequired for an empty path. It does not ping, migrate or wrap the pool in a store; the caller closes the pool.

Types

type Options

type Options struct {
	// BusyTimeout bounds lock waits; 10s when zero.
	BusyTimeout time.Duration
}

Options configures DSN and OpenDB.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL