sqlitex

package
v0.5.5 Latest Latest
Warning

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

 Go to latest Published: Aug 20, 2024 License: ISC Imports: 12 Imported by: 8

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 deprecated 

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 ExecFS deprecated 

func ExecFS(conn *sqlite.Conn, fsys fs.FS, filename string, opts *ExecOptions) error

ExecFS is an alias for ExecuteFS.

Deprecated: Call ExecuteFS directly.

func ExecScript 

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

ExecScript executes a script of SQL statements. It is the same as calling ExecuteScript without options.

func ExecScriptFS deprecated 

func ExecScriptFS(conn *sqlite.Conn, fsys fs.FS, filename string, opts *ExecOptions) (err error)

ExecScriptFS is an alias for ExecuteScriptFS.

Deprecated: Call ExecuteScriptFS directly.

func ExecTransient deprecated 

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 

func ExecTransientFS(conn *sqlite.Conn, fsys fs.FS, filename string, opts *ExecOptions) error

ExecTransientFS is an alias for ExecuteTransientFS.

Deprecated: Call ExecuteTransientFS directly.

func Execute 

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 

func ExecuteFS(conn *sqlite.Conn, fsys fs.FS, filename string, opts *ExecOptions) error

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 

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 

func ExecuteScriptFS(conn *sqlite.Conn, fsys fs.FS, filename string, opts *ExecOptions) (err error)

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 

func ExecuteTransientFS(conn *sqlite.Conn, fsys fs.FS, filename string, opts *ExecOptions) error

ExecuteTransientFS executes the single statement in the given SQL file without caching the underlying query.

func NewBlobSeeker 

func NewBlobSeeker(blob *sqlite.Blob) *blobSeeker

This wraps a sqlite.Blob with positional state provide extra io implementations.

func PrepareTransientFS 

func PrepareTransientFS(conn *sqlite.Conn, fsys fs.FS, filename string) (*sqlite.Stmt, error)

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 

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 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 

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.