Documentation
¶
Overview ¶
Package sqlitex provides utilities for working with SQLite.
Index ¶
- Variables
- func Exec(conn *sqlite.Conn, query string, resultFn func(stmt *sqlite.Stmt) error, ...) error
- func ExecScript(conn *sqlite.Conn, queries string) (err error)
- func ExecTransient(conn *sqlite.Conn, query string, resultFn func(stmt *sqlite.Stmt) error, ...) (err error)
- func InsertRandID(stmt *sqlite.Stmt, param string, min, max int64) (id int64, err error)
- func ResultFloat(stmt *sqlite.Stmt) (float64, error)
- func ResultInt(stmt *sqlite.Stmt) (int, error)
- func ResultInt64(stmt *sqlite.Stmt) (int64, error)
- func ResultText(stmt *sqlite.Stmt) (string, error)
- func Save(conn *sqlite.Conn) (releaseFn func(*error))
- type Buffer
- func (bb *Buffer) Cap() (n int64)
- func (bb *Buffer) Close() error
- func (bb *Buffer) Len() (n int64)
- func (bb *Buffer) Read(p []byte) (n int, err error)
- func (bb *Buffer) ReadByte() (byte, error)
- func (bb *Buffer) Reset()
- func (bb *Buffer) UnreadByte() error
- func (bb *Buffer) Write(p []byte) (n int, err error)
- func (bb *Buffer) WriteByte(c byte) error
- func (bb *Buffer) WriteString(p string) (n int, err error)
- type File
- type Pool
Constants ¶
This section is empty.
Variables ¶
var ErrMultipleResults = errors.New("sqlite: statement has multiple result rows")
var ErrNoResults = errors.New("sqlite: statement has no results")
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 ¶
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 ¶
InsertRandID executes stmt with a random value in the range [min, max) for $param.
func ResultFloat ¶
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 ¶
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 ¶
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 ¶
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 ¶
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
}
Types ¶
type Buffer ¶
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 NewBufferSize ¶
NewBufferSize creates a Buffer with a specified page size.
func (*Buffer) UnreadByte ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
Source Files