sqlite: crawshaw.io/sqlite/sqlitex Index | Files

package sqlitex

import "crawshaw.io/sqlite/sqlitex"

Package sqlitex provides utilities for working with SQLite.


Package Files

buffer.go exec.go file.go pool.go query.go rand_id.go savepoint.go snapshot.go


var PoolCloseTimeout = 5 * time.Second

PoolCloseTimeout is the

func Exec Uses

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 := sqlutil.Exec(conn, "SELECT a, b FROM t WHERE c = ? AND d = ?;", fn, 42, 1)
if err != nil {
	// handle err

func ExecScript Uses

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 Uses

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 Uses

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 Uses

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

func ResultInt Uses

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

func ResultInt64 Uses

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

func ResultText Uses

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

func Save Uses

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.


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

	// ... do work in the transaction


type Buffer Uses

type Buffer struct {
    // 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 Uses

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

NewBuffer creates a Buffer with 16KB pages.

func NewBufferSize Uses

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

NewBufferSize creates a Buffer with a specified page size.

func (*Buffer) Cap Uses

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

func (*Buffer) Close Uses

func (bb *Buffer) Close() error

func (*Buffer) Len Uses

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

func (*Buffer) Read Uses

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

func (*Buffer) ReadByte Uses

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

func (*Buffer) Reset Uses

func (bb *Buffer) Reset()

func (*Buffer) UnreadByte Uses

func (bb *Buffer) UnreadByte() error

func (*Buffer) Write Uses

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

func (*Buffer) WriteByte Uses

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

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

func (*Buffer) WriteString Uses

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

type File Uses

type File struct {
    // contains filtered or unexported fields

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

func NewFile Uses

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

func NewFileSize Uses

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

func (*File) Cap Uses

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

func (*File) Close Uses

func (bb *File) Close() error

func (*File) Len Uses

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

func (*File) Read Uses

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

func (*File) Seek Uses

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

func (*File) Truncate Uses

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

func (*File) Write Uses

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

type Pool Uses

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 Uses

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:


func (*Pool) Close Uses

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 Uses

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 Uses

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 Uses

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.

Package sqlitex imports 13 packages (graph) and is imported by 45 packages. Updated 2020-03-11. Refresh now. Tools for package owners.