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, ...) errordeprecated
- func ExecFS(conn *sqlite.Conn, fsys fs.FS, filename string, opts *ExecOptions) errordeprecated
- func ExecScript(conn *sqlite.Conn, queries string) (err error)
- func ExecScriptFS(conn *sqlite.Conn, fsys fs.FS, filename string, opts *ExecOptions) (err error)deprecated
- func ExecTransient(conn *sqlite.Conn, query string, resultFn func(stmt *sqlite.Stmt) error, ...) (err error)deprecated
- func ExecTransientFS(conn *sqlite.Conn, fsys fs.FS, filename string, opts *ExecOptions) errordeprecated
- func Execute(conn *sqlite.Conn, query string, opts *ExecOptions) error
- func ExecuteFS(conn *sqlite.Conn, fsys fs.FS, filename string, opts *ExecOptions) error
- func ExecuteScript(conn *sqlite.Conn, queries string, opts *ExecOptions) (err error)
- func ExecuteScriptFS(conn *sqlite.Conn, fsys fs.FS, filename string, opts *ExecOptions) (err error)
- func ExecuteTransient(conn *sqlite.Conn, query string, opts *ExecOptions) (err error)
- func ExecuteTransientFS(conn *sqlite.Conn, fsys fs.FS, filename string, opts *ExecOptions) error
- func NewBlobSeeker(blob *sqlite.Blob) *blobSeeker
- func PrepareTransientFS(conn *sqlite.Conn, fsys fs.FS, filename string) (*sqlite.Stmt, 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 ExecOptions
- 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
deprecated
added in
v0.7.0
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.
Deprecated: Use Execute. Exec skips some argument checks for compatibility with crawshaw.io/sqlite.
func ExecScript ¶ added in v0.7.0
ExecScript executes a script of SQL statements. It is the same as calling ExecuteScript without options.
func ExecScriptFS
deprecated
added in
v0.7.0
func ExecTransient
deprecated
added in
v0.7.0
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.
Deprecated: Use ExecuteTransient. ExecTransient skips some argument checks for compatibility with crawshaw.io/sqlite.
func ExecTransientFS
deprecated
added in
v0.7.0
func Execute ¶ added in v0.7.0
func Execute(conn *sqlite.Conn, query string, opts *ExecOptions) error
Execute executes an SQLite query.
As Execute is implemented using Conn.Prepare, subsequent calls to Execute with the same statement will reuse the cached statement object.
func ExecuteFS ¶ added in v0.7.0
ExecuteFS executes the single statement in the given SQL file. ExecuteFS is implemented using Conn.Prepare, so subsequent calls to ExecuteFS with the same statement will reuse the cached statement object.
func ExecuteScript ¶ added in v0.7.0
func ExecuteScript(conn *sqlite.Conn, queries string, opts *ExecOptions) (err error)
ExecuteScript executes a script of SQL statements. The script is wrapped in a SAVEPOINT transaction, which is rolled back on any error.
opts.ResultFunc is ignored.
func ExecuteScriptFS ¶ added in v0.7.0
ExecuteScriptFS executes a script of SQL statements from a file. The script is wrapped in a SAVEPOINT transaction, which is rolled back on any error.
func ExecuteTransient ¶
func ExecuteTransient(conn *sqlite.Conn, query string, opts *ExecOptions) (err error)
ExecuteTransient executes an SQLite query without caching the underlying query. It is the spiritual equivalent of sqlite3_exec: https://www.sqlite.org/c3ref/exec.html
func ExecuteTransientFS ¶ added in v0.7.0
ExecuteTransientFS executes the single statement in the given SQL file without caching the underlying query.
func NewBlobSeeker ¶ added in v0.7.0
This wraps a sqlite.Blob with positional state provide extra io implementations.
func PrepareTransientFS ¶ added in v0.7.0
PrepareTransientFS prepares an SQL statement from a file that is not cached by the Conn. Subsequent calls with the same query will create new Stmts. The caller is responsible for calling Finalize on the returned Stmt when the Stmt is no longer needed.
func ResultFloat ¶ added in v0.7.0
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 ¶ added in v0.7.0
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 ¶ added in v0.7.0
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 ¶ added in v0.7.0
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 ¶ added in v0.7.0
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 ExecOptions ¶
type ExecOptions struct {
// Args is the set of positional arguments to bind to the statement.
// The first element in the slice is ?1.
// See https://sqlite.org/lang_expr.html for more details.
//
// 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.Sprint(v) and passed to BindText.
Args []interface{}
// Named is the set of named arguments to bind to the statement. Keys must
// start with ':', '@', or '$'. See https://sqlite.org/lang_expr.html for more
// details.
//
// Basic reflection on Named 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.Sprint(v) and passed to BindText.
Named map[string]interface{}
// ResultFunc is called for each result row.
// If ResultFunc returns an error then iteration ceases
// and the execution function returns the error value.
ResultFunc func(stmt *sqlite.Stmt) error
// Allow unused parameters. SQLite normally treats these as null anyway, so this reverts to the
// default behaviour.
AllowUnused bool
}
ExecOptions is the set of optional arguments executing a statement.
type Pool ¶ added in v0.7.0
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 ¶ added in v0.7.0
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 ¶ added in v0.7.0
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 ¶ added in v0.7.0
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 ¶ added in v0.7.0
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 ¶ added in v0.7.0
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