Documentation
¶
Overview ¶
Package sqlite provides SQLite connection management and schema migration utilities for hamr-scaffolded projects.
It uses the pure-Go modernc.org/sqlite driver so projects compile without CGO. The package mirrors pkg/db's API shape (ConnectContext, Migrate, ...) with simpler semantics appropriate for a local-file database: no retries, no pool tuning. Defaults: WAL, foreign keys on, 5s busy timeout, in-memory temp store, 64 MB journal size limit and immediate transactions (_txlock=immediate). Any other pragma can be set with WithPragma, and PRAGMA optimize runs once after connecting.
Index ¶
- func Connect(path string, opts ...ConnectOption) (*sqlx.DB, error)
- func ConnectContext(ctx context.Context, path string, opts ...ConnectOption) (*sqlx.DB, error)
- func Migrate(db *sqlx.DB, cfg MigrateConfig) error
- func MigrateDown(db *sqlx.DB, cfg MigrateConfig) error
- func MigrateForce(db *sqlx.DB, cfg MigrateConfig, version int) error
- func MigrateSteps(db *sqlx.DB, cfg MigrateConfig, n int) error
- func MigrateVersion(db *sqlx.DB, cfg MigrateConfig) (version uint, dirty bool, err error)
- type ConnectConfig
- type ConnectOption
- type MigrateConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Connect ¶
func Connect(path string, opts ...ConnectOption) (*sqlx.DB, error)
Connect opens a SQLite database file using context.Background().
func ConnectContext ¶
ConnectContext opens a SQLite database file, ensuring the parent directory exists and applying the configured pragmas on every connection. It then validates connectivity via PingContext.
func Migrate ¶
func Migrate(db *sqlx.DB, cfg MigrateConfig) error
Migrate runs all up migrations from the embedded filesystem. migrate.ErrNoChange is silently ignored.
func MigrateDown ¶
func MigrateDown(db *sqlx.DB, cfg MigrateConfig) error
MigrateDown rolls back all migrations.
func MigrateForce ¶
func MigrateForce(db *sqlx.DB, cfg MigrateConfig, version int) error
MigrateForce sets the migration version without running any migrations. Use this to fix a dirty migration state.
func MigrateSteps ¶
func MigrateSteps(db *sqlx.DB, cfg MigrateConfig, n int) error
MigrateSteps runs n migration steps. Positive n migrates up, negative migrates down.
func MigrateVersion ¶
MigrateVersion returns the current migration version and dirty flag.
Types ¶
type ConnectConfig ¶
type ConnectConfig struct {
// JournalMode sets PRAGMA journal_mode. Default "WAL".
JournalMode string
// ForeignKeys toggles PRAGMA foreign_keys. Default true.
ForeignKeys bool
// BusyTimeout sets PRAGMA busy_timeout. Default 5s.
BusyTimeout time.Duration
// MaxOpenConns caps the connection pool. Default 1 — SQLite is
// single-writer, so higher values only help read-heavy workloads on WAL.
MaxOpenConns int
// TxLock sets the driver's _txlock DSN parameter (deferred, immediate or
// exclusive). Default "immediate"; empty omits the parameter (driver
// default, deferred).
TxLock string
// Pragmas are extra or overriding pragmas. Order only decides which value
// wins for a duplicate name; the driver sets execution order (busy_timeout
// first, then alphabetical). See WithPragma.
Pragmas [][2]string
}
ConnectConfig holds connection parameters.
type ConnectOption ¶
type ConnectOption func(*ConnectConfig)
ConnectOption configures a ConnectConfig.
func WithBusyTimeout ¶
func WithBusyTimeout(d time.Duration) ConnectOption
WithBusyTimeout overrides PRAGMA busy_timeout.
func WithForeignKeys ¶
func WithForeignKeys(enabled bool) ConnectOption
WithForeignKeys toggles PRAGMA foreign_keys.
func WithJournalMode ¶
func WithJournalMode(mode string) ConnectOption
WithJournalMode overrides PRAGMA journal_mode.
func WithMaxOpenConns ¶
func WithMaxOpenConns(n int) ConnectOption
WithMaxOpenConns overrides the connection pool cap.
func WithPragma ¶ added in v0.46.0
func WithPragma(name, value string) ConnectOption
WithPragma sets any SQLite pragma on every pooled connection. If name is one hamr already sets (journal_mode, foreign_keys, busy_timeout, temp_store, journal_size_limit) the value replaces hamr's; otherwise it is appended. A later call for the same name wins. The driver runs pragmas in its own order (busy_timeout first, then alphabetical), so order-sensitive pragmas such as page_size will not take effect on a new WAL database. SQLite silently ignores unknown pragma names and invalid values; check with PRAGMA name if unsure. Examples:
sqlite.WithPragma("cache_size", "-20000") // negative = KiB, so ~20 MB
sqlite.WithPragma("synchronous", "NORMAL")
synchronous=NORMAL in WAL mode is faster, but the last commits can be lost on power loss (the database itself cannot be corrupted).
func WithTxLock ¶ added in v0.46.0
func WithTxLock(mode string) ConnectOption
WithTxLock sets the transaction locking mode (_txlock): "deferred", "immediate" or "exclusive". The default is "immediate", so a transaction takes the write lock at BEGIN instead of failing instantly with SQLITE_BUSY when two deferred transactions both try to upgrade to write. An empty string omits the parameter and uses the driver default (deferred).
type MigrateConfig ¶
MigrateConfig configures the migration runner.
Source Files