sqlitex

README

SQLiteX

Getting Started

go get github.com/gulitsky/sqlitex

Documentation

Index

• func Maintain(ctx context.Context, db *sql.DB, options ...maintenanceOption) error
• func Open(driverName string, dataSourceName string, preemptive ...string) (*sql.DB, error)
• func OpenMemory(driverName string, options ...option) (*sql.DB, error)
• func OpenReadOnly(driverName string, filePath string, options ...option) (*sql.DB, error)
• func OpenReadWrite(driverName string, filePath string, options ...option) (*sql.DB, error)
• func WithBusyTimeout(timeout time.Duration) option
• func WithCacheSizeKiB(size uint64) option
• func WithCheckpointPeriod(period time.Duration) maintenanceOption
• func WithLogger(logger *slog.Logger) maintenanceOption
• func WithMemoryMapSize(size uint64) option
• func WithOptimizePeriod(period time.Duration) maintenanceOption
• func WithPragma(name, value string) option
• func WithWALAutoCheckpoint(pages uint64) option

Functions

func Maintain

func Maintain(ctx context.Context, db *sql.DB, options ...maintenanceOption) error

Maintain starts a background maintenance loop for the database. It performs periodic WAL checkpoints and optimizations. It returns only when ctx is canceled or a fatal error occurs during final checkpoint.

func Open

func Open(driverName string, dataSourceName string, preemptive ...string) (*sql.DB, error)

func OpenMemory

func OpenMemory(driverName string, options ...option) (*sql.DB, error)

OpenMemory opens a new shared memory database. Each call creates a distinct database unless a specific name is provided via custom options (not yet supported).

func OpenReadOnly

func OpenReadOnly(driverName string, filePath string, options ...option) (*sql.DB, error)

OpenReadOnly opens a database in read-only mode. It sets "query_only=yes" and optimizes cache for reading.

The connection pool is sized based on GOMAXPROCS.

func OpenReadWrite

func OpenReadWrite(driverName string, filePath string, options ...option) (*sql.DB, error)

OpenReadWrite opens a database in read-write mode. It sets "mode=rwc", "txlock=immediate", and strictly limits concurrency to 1 connection to avoid SQLITE_BUSY errors during transaction upgrades.

func WithBusyTimeout

func WithBusyTimeout(timeout time.Duration) option

WithBusyTimeout sets the busy_timeout pragma.

func WithCacheSizeKiB

func WithCacheSizeKiB(size uint64) option

WithCacheSizeKiB sets the cache_size pragma (in KiB).

func WithCheckpointPeriod

func WithCheckpointPeriod(period time.Duration) maintenanceOption

WithCheckpointPeriod sets the interval for PRAGMA wal_checkpoint(PASSIVE).

func WithLogger

func WithLogger(logger *slog.Logger) maintenanceOption

WithLogger sets the structured logger for maintenance events.

func WithMemoryMapSize

func WithMemoryMapSize(size uint64) option

WithMemoryMapSize sets the mmap_size pragma.

func WithOptimizePeriod

func WithOptimizePeriod(period time.Duration) maintenanceOption

WithOptimizePeriod sets the interval for PRAGMA optimize.

func WithPragma

func WithPragma(name, value string) option

WithPragma adds or overrides a specific SQLite pragma.

func WithWALAutoCheckpoint

func WithWALAutoCheckpoint(pages uint64) option

WithWALAutoCheckpoint sets the wal_autocheckpoint pragma (number of pages).