sqlitex

package
v0.0.0-...-0d0e370 Latest Latest
Warning

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

Go to latest
Published: Dec 6, 2022 License: ISC Imports: 13 Imported by: 0

Documentation

Overview

Package sqlitex provides utilities for working with SQLite.

Index

Constants

This section is empty.

Variables

View Source
var ErrMultipleResults = errors.New("sqlite: statement has multiple result rows")
View Source
var ErrNoResults = errors.New("sqlite: statement has no results")
View Source
var PoolCloseTimeout = 5 * time.Second

PoolCloseTimeout is the maximum time for Pool.Close to wait for all Conns to be returned to the Pool.

Do not modify this concurrently with calling Pool.Close.

Functions

func Exec

func Exec(conn *sqlite.Conn, query string, resultFn func(stmt *sqlite.Stmt) error, args ...interface{}) error

Exec executes an SQLite query.

For each result row, the resultFn is called. Result values can be read by resultFn using stmt.Column* methods. If resultFn returns an error then iteration ceases and Exec returns the error value.

Any args provided to Exec are bound to numbered parameters of the query using the Stmt Bind* methods. Basic reflection on args is used to map:

integers to BindInt64
floats   to BindFloat
[]byte   to BindBytes
string   to BindText
bool     to BindBool

All other kinds are printed using fmt.Sprintf("%v", v) and passed to BindText.

Exec is implemented using the Stmt prepare mechanism which allows better interactions with Go's type system and avoids pitfalls of passing a Go closure to cgo.

As Exec is implemented using Conn.Prepare, subsequent calls to Exec with the same statement will reuse the cached statement object.

Typical use:

conn := dbpool.Get()
defer dbpool.Put(conn)

if err := sqlitex.Exec(conn, "INSERT INTO t (a, b, c, d) VALUES (?, ?, ?, ?);", nil, "a1", 1, 42, 1); err != nil {
	// handle err
}

var a []string
var b []int64
fn := func(stmt *sqlite.Stmt) error {
	a = append(a, stmt.ColumnText(0))
	b = append(b, stmt.ColumnInt64(1))
	return nil
}
err := sqlitex.Exec(conn, "SELECT a, b FROM t WHERE c = ? AND d = ?;", fn, 42, 1)
if err != nil {
	// handle err
}

func ExecScript

func ExecScript(conn *sqlite.Conn, queries string) (err error)

ExecScript executes a script of SQL statements.

The script is wrapped in a SAVEPOINT transaction, which is rolled back on any error.

func ExecTransient

func ExecTransient(conn *sqlite.Conn, query string, resultFn func(stmt *sqlite.Stmt) error, args ...interface{}) (err error)

ExecTransient executes an SQLite query without caching the underlying query. The interface is exactly the same as Exec.

It is the spiritual equivalent of sqlite3_exec.

func InsertRandID

func InsertRandID(stmt *sqlite.Stmt, param string, min, max int64) (id int64, err error)

InsertRandID executes stmt with a random value in the range [min, max) for $param.

func ResultFloat

func ResultFloat(stmt *sqlite.Stmt) (float64, error)

ResultFloat steps the Stmt once and returns the first column as a float64.

If there are no rows in the result set, ErrNoResults is returned.

If there are multiple rows, ErrMultipleResults is returned with the first result.

The Stmt is always Reset, so repeated calls will always return the first result.

func ResultInt

func ResultInt(stmt *sqlite.Stmt) (int, error)

ResultInt steps the Stmt once and returns the first column as an int.

If there are no rows in the result set, ErrNoResults is returned.

If there are multiple rows, ErrMultipleResults is returned with the first result.

The Stmt is always Reset, so repeated calls will always return the first result.

func ResultInt64

func ResultInt64(stmt *sqlite.Stmt) (int64, error)

ResultInt64 steps the Stmt once and returns the first column as an int64.

If there are no rows in the result set, ErrNoResults is returned.

If there are multiple rows, ErrMultipleResults is returned with the first result.

The Stmt is always Reset, so repeated calls will always return the first result.

func ResultText

func ResultText(stmt *sqlite.Stmt) (string, error)

ResultText steps the Stmt once and returns the first column as a string.

If there are no rows in the result set, ErrNoResults is returned.

If there are multiple rows, ErrMultipleResults is returned with the first result.

The Stmt is always Reset, so repeated calls will always return the first result.

func Save

func Save(conn *sqlite.Conn) (releaseFn func(*error))

Save creates a named SQLite transaction using SAVEPOINT.

On success Savepoint returns a releaseFn that will call either RELEASE or ROLLBACK depending on whether the parameter *error points to a nil or non-nil error. This is designed to be deferred.

Example:

func doWork(conn *sqlite.Conn) (err error) {
	defer sqlitex.Save(conn)(&err)

	// ... do work in the transaction
}

https://www.sqlite.org/lang_savepoint.html

Types

type Buffer

type Buffer struct {
	io.Reader
	io.Writer
	io.ByteScanner
	// contains filtered or unexported fields
}

A Buffer is a variable-sized bytes buffer backed by SQLite blobs.

The bytes are broken into pages, with the first and last pages stored in memory, and intermediate pages loaded into blobs. Unlike a single SQLite blob, a Buffer can grow beyond its initial size. The blobs are allocated in a temporary table.

A Buffer is very similar to a bytes.Buffer.

func NewBuffer

func NewBuffer(conn *sqlite.Conn) (*Buffer, error)

NewBuffer creates a Buffer with 16KB pages.

func NewBufferSize

func NewBufferSize(conn *sqlite.Conn, pageSize int) (*Buffer, error)

NewBufferSize creates a Buffer with a specified page size.

func (*Buffer) Cap

func (bb *Buffer) Cap() (n int64)

func (*Buffer) Close

func (bb *Buffer) Close() error

func (*Buffer) Len

func (bb *Buffer) Len() (n int64)

func (*Buffer) Read

func (bb *Buffer) Read(p []byte) (n int, err error)

func (*Buffer) ReadByte

func (bb *Buffer) ReadByte() (byte, error)

func (*Buffer) Reset

func (bb *Buffer) Reset()

func (*Buffer) UnreadByte

func (bb *Buffer) UnreadByte() error

func (*Buffer) Write

func (bb *Buffer) Write(p []byte) (n int, err error)

func (*Buffer) WriteByte

func (bb *Buffer) WriteByte(c byte) error

WriteByte appends a byte to the buffer, growing it as needed.

func (*Buffer) WriteString

func (bb *Buffer) WriteString(p string) (n int, err error)

type File

type File struct {
	io.Reader
	io.Writer
	io.Seeker
	// contains filtered or unexported fields
}

File is a readable, writable, and seekable series of temporary SQLite blobs.

func NewFile

func NewFile(conn *sqlite.Conn) (*File, error)

func NewFileSize

func NewFileSize(conn *sqlite.Conn, initSize int) (*File, error)

func (*File) Cap

func (bb *File) Cap() (n int64)

func (*File) Close

func (bb *File) Close() error

func (*File) Len

func (bb *File) Len() (n int64)

func (*File) Read

func (bb *File) Read(p []byte) (n int, err error)

func (*File) Seek

func (bb *File) Seek(offset int64, whence int) (int64, error)

func (*File) Truncate

func (bb *File) Truncate(size int64) error

func (*File) Write

func (bb *File) Write(p []byte) (n int, err error)

type Pool

type Pool struct {
	// contains filtered or unexported fields
}

Pool is a pool of SQLite connections.

It is safe for use by multiple goroutines concurrently.

Typically, a goroutine that needs to use an SQLite *Conn Gets it from the pool and defers its return:

conn := dbpool.Get(nil)
defer dbpool.Put(conn)

As Get may block, a context can be used to return if a task is cancelled. In this case the Conn returned will be nil:

conn := dbpool.Get(ctx)
if conn == nil {
	return context.Canceled
}
defer dbpool.Put(conn)

func Open

func Open(uri string, flags sqlite.OpenFlags, poolSize int) (pool *Pool, err error)

Open opens a fixed-size pool of SQLite connections.

A flags value of 0 defaults to:

SQLITE_OPEN_READWRITE
SQLITE_OPEN_CREATE
SQLITE_OPEN_WAL
SQLITE_OPEN_URI
SQLITE_OPEN_NOMUTEX

func OpenInit

func OpenInit(ctx context.Context, uri string, flags sqlite.OpenFlags, poolSize int, initScript string) (pool *Pool, err error)

OpenInit opens a fixed-size pool of SQLite connections, each initialized with initScript.

A flags value of 0 defaults to:

SQLITE_OPEN_READWRITE
SQLITE_OPEN_CREATE
SQLITE_OPEN_WAL
SQLITE_OPEN_URI
SQLITE_OPEN_NOMUTEX

Each initScript is run an all Conns in the Pool. This is intended for PRAGMA or CREATE TEMP VIEW which need to be run on all connections.

WARNING: Ensure all queries in initScript are completely idempotent, meaning that running it multiple times is the same as running it once. For example do not run INSERT in any of the initScripts or else it may create duplicate data unintentionally or fail.

func (*Pool) Close

func (p *Pool) Close() (err error)

Close interrupts and closes all the connections in the Pool.

Close blocks until all connections are returned to the Pool.

Close will panic if not all connections are returned before PoolCloseTimeout.

func (*Pool) Get

func (p *Pool) Get(ctx context.Context) *sqlite.Conn

Get returns an SQLite connection from the Pool.

If no Conn is available, Get will block until one is, or until either the Pool is closed or the context expires. If no Conn can be obtained, nil is returned.

The provided context is used to control the execution lifetime of the connection. See Conn.SetInterrupt for details.

Applications must ensure that all non-nil Conns returned from Get are returned to the same Pool with Put.

func (*Pool) GetSnapshot

func (p *Pool) GetSnapshot(ctx context.Context, schema string) (*sqlite.Snapshot, error)

GetSnapshot returns a Snapshot that should remain available for reads until it is garbage collected.

This sets aside a Conn from the Pool with an open read transaction until the Snapshot is garbage collected or the Pool is closed. Thus, until the returned Snapshot is garbage collected, the Pool will have one fewer Conn, and it should not be possible for the WAL to be checkpointed beyond the point of the Snapshot.

See sqlite.Conn.GetSnapshot and sqlite.Snapshot for more details.

func (*Pool) Put

func (p *Pool) Put(conn *sqlite.Conn)

Put puts an SQLite connection back into the Pool.

Put will panic if conn is nil or if the conn was not originally created by p.

Applications must ensure that all non-nil Conns returned from Get are returned to the same Pool with Put.

Jump to

Keyboard shortcuts

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