sqlite

package module
v0.0.0-...-832d6b7 Latest Latest
Warning

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

Go to latest
Published: Aug 16, 2023 License: ISC, MIT Imports: 10 Imported by: 19

README

SQLite Extensions

Go v1.14 CGO Godoc

Overview

sqlite package provides a low-level interface that allows you to build sqlite extensions that can be loaded dynamically at runtime or linked statically at build-time (experimental)

Installation

This package can be installed with go get as:

$ go get -u go.riyazali.net/sqlite

sqlite is a cgo package and requires a working c compiler.

Usage

To build an sqlite extension, you need to build your project with -buildmode=c-shared. That would emit a .so file (or .dll on windows), which you can then load into sqlite.

Consider as an example, the sample upper module in _examples/. To build it, you'd use something similar to:

$ go build -buildmode=c-shared -o upper.so _examples/upper

which would emit an upper.so in the current directory. Now, to use it with (say) the sqlite3 shell, you could do something like

$ sqlite3
> .load upper.so
> SELECT upper("sqlite3");
SQLITE3
> .exit

Features

Each of the support feature provides an exported interface that the user code must implement. Refer to code and godoc for more details.

License

MIT License Copyright (c) 2020 Riyaz Ali

Refer to LICENSE for full text.

Documentation

Overview

Package sqlite provides a Go wrapper over sqlite3's loadable extension interface.

Index

Constants

View Source
const (
	SQLITE_OK         = ErrorCode(C.SQLITE_OK) // do not use in Error
	SQLITE_ERROR      = ErrorCode(C.SQLITE_ERROR)
	SQLITE_INTERNAL   = ErrorCode(C.SQLITE_INTERNAL)
	SQLITE_PERM       = ErrorCode(C.SQLITE_PERM)
	SQLITE_ABORT      = ErrorCode(C.SQLITE_ABORT)
	SQLITE_BUSY       = ErrorCode(C.SQLITE_BUSY)
	SQLITE_LOCKED     = ErrorCode(C.SQLITE_LOCKED)
	SQLITE_NOMEM      = ErrorCode(C.SQLITE_NOMEM)
	SQLITE_READONLY   = ErrorCode(C.SQLITE_READONLY)
	SQLITE_INTERRUPT  = ErrorCode(C.SQLITE_INTERRUPT)
	SQLITE_IOERR      = ErrorCode(C.SQLITE_IOERR)
	SQLITE_CORRUPT    = ErrorCode(C.SQLITE_CORRUPT)
	SQLITE_NOTFOUND   = ErrorCode(C.SQLITE_NOTFOUND)
	SQLITE_FULL       = ErrorCode(C.SQLITE_FULL)
	SQLITE_CANTOPEN   = ErrorCode(C.SQLITE_CANTOPEN)
	SQLITE_PROTOCOL   = ErrorCode(C.SQLITE_PROTOCOL)
	SQLITE_EMPTY      = ErrorCode(C.SQLITE_EMPTY)
	SQLITE_SCHEMA     = ErrorCode(C.SQLITE_SCHEMA)
	SQLITE_TOOBIG     = ErrorCode(C.SQLITE_TOOBIG)
	SQLITE_CONSTRAINT = ErrorCode(C.SQLITE_CONSTRAINT)
	SQLITE_MISMATCH   = ErrorCode(C.SQLITE_MISMATCH)
	SQLITE_MISUSE     = ErrorCode(C.SQLITE_MISUSE)
	SQLITE_NOLFS      = ErrorCode(C.SQLITE_NOLFS)
	SQLITE_AUTH       = ErrorCode(C.SQLITE_AUTH)
	SQLITE_FORMAT     = ErrorCode(C.SQLITE_FORMAT)
	SQLITE_RANGE      = ErrorCode(C.SQLITE_RANGE)
	SQLITE_NOTADB     = ErrorCode(C.SQLITE_NOTADB)
	SQLITE_NOTICE     = ErrorCode(C.SQLITE_NOTICE)
	SQLITE_WARNING    = ErrorCode(C.SQLITE_WARNING)
	SQLITE_ROW        = ErrorCode(C.SQLITE_ROW)  // do not use in Error
	SQLITE_DONE       = ErrorCode(C.SQLITE_DONE) // do not use in Error

	SQLITE_ERROR_MISSING_COLLSEQ   = ErrorCode(C.SQLITE_ERROR_MISSING_COLLSEQ)
	SQLITE_ERROR_RETRY             = ErrorCode(C.SQLITE_ERROR_RETRY)
	SQLITE_ERROR_SNAPSHOT          = ErrorCode(C.SQLITE_ERROR_SNAPSHOT)
	SQLITE_IOERR_READ              = ErrorCode(C.SQLITE_IOERR_READ)
	SQLITE_IOERR_SHORT_READ        = ErrorCode(C.SQLITE_IOERR_SHORT_READ)
	SQLITE_IOERR_WRITE             = ErrorCode(C.SQLITE_IOERR_WRITE)
	SQLITE_IOERR_FSYNC             = ErrorCode(C.SQLITE_IOERR_FSYNC)
	SQLITE_IOERR_DIR_FSYNC         = ErrorCode(C.SQLITE_IOERR_DIR_FSYNC)
	SQLITE_IOERR_TRUNCATE          = ErrorCode(C.SQLITE_IOERR_TRUNCATE)
	SQLITE_IOERR_FSTAT             = ErrorCode(C.SQLITE_IOERR_FSTAT)
	SQLITE_IOERR_UNLOCK            = ErrorCode(C.SQLITE_IOERR_UNLOCK)
	SQLITE_IOERR_RDLOCK            = ErrorCode(C.SQLITE_IOERR_RDLOCK)
	SQLITE_IOERR_DELETE            = ErrorCode(C.SQLITE_IOERR_DELETE)
	SQLITE_IOERR_BLOCKED           = ErrorCode(C.SQLITE_IOERR_BLOCKED)
	SQLITE_IOERR_NOMEM             = ErrorCode(C.SQLITE_IOERR_NOMEM)
	SQLITE_IOERR_ACCESS            = ErrorCode(C.SQLITE_IOERR_ACCESS)
	SQLITE_IOERR_CHECKRESERVEDLOCK = ErrorCode(C.SQLITE_IOERR_CHECKRESERVEDLOCK)
	SQLITE_IOERR_LOCK              = ErrorCode(C.SQLITE_IOERR_LOCK)
	SQLITE_IOERR_CLOSE             = ErrorCode(C.SQLITE_IOERR_CLOSE)
	SQLITE_IOERR_DIR_CLOSE         = ErrorCode(C.SQLITE_IOERR_DIR_CLOSE)
	SQLITE_IOERR_SHMOPEN           = ErrorCode(C.SQLITE_IOERR_SHMOPEN)
	SQLITE_IOERR_SHMSIZE           = ErrorCode(C.SQLITE_IOERR_SHMSIZE)
	SQLITE_IOERR_SHMLOCK           = ErrorCode(C.SQLITE_IOERR_SHMLOCK)
	SQLITE_IOERR_SHMMAP            = ErrorCode(C.SQLITE_IOERR_SHMMAP)
	SQLITE_IOERR_SEEK              = ErrorCode(C.SQLITE_IOERR_SEEK)
	SQLITE_IOERR_DELETE_NOENT      = ErrorCode(C.SQLITE_IOERR_DELETE_NOENT)
	SQLITE_IOERR_MMAP              = ErrorCode(C.SQLITE_IOERR_MMAP)
	SQLITE_IOERR_GETTEMPPATH       = ErrorCode(C.SQLITE_IOERR_GETTEMPPATH)
	SQLITE_IOERR_CONVPATH          = ErrorCode(C.SQLITE_IOERR_CONVPATH)
	SQLITE_IOERR_VNODE             = ErrorCode(C.SQLITE_IOERR_VNODE)
	SQLITE_IOERR_AUTH              = ErrorCode(C.SQLITE_IOERR_AUTH)
	SQLITE_IOERR_BEGIN_ATOMIC      = ErrorCode(C.SQLITE_IOERR_BEGIN_ATOMIC)
	SQLITE_IOERR_COMMIT_ATOMIC     = ErrorCode(C.SQLITE_IOERR_COMMIT_ATOMIC)
	SQLITE_IOERR_ROLLBACK_ATOMIC   = ErrorCode(C.SQLITE_IOERR_ROLLBACK_ATOMIC)
	SQLITE_LOCKED_SHAREDCACHE      = ErrorCode(C.SQLITE_LOCKED_SHAREDCACHE)
	SQLITE_BUSY_RECOVERY           = ErrorCode(C.SQLITE_BUSY_RECOVERY)
	SQLITE_BUSY_SNAPSHOT           = ErrorCode(C.SQLITE_BUSY_SNAPSHOT)
	SQLITE_CANTOPEN_NOTEMPDIR      = ErrorCode(C.SQLITE_CANTOPEN_NOTEMPDIR)
	SQLITE_CANTOPEN_ISDIR          = ErrorCode(C.SQLITE_CANTOPEN_ISDIR)
	SQLITE_CANTOPEN_FULLPATH       = ErrorCode(C.SQLITE_CANTOPEN_FULLPATH)
	SQLITE_CANTOPEN_CONVPATH       = ErrorCode(C.SQLITE_CANTOPEN_CONVPATH)
	SQLITE_CORRUPT_VTAB            = ErrorCode(C.SQLITE_CORRUPT_VTAB)
	SQLITE_READONLY_RECOVERY       = ErrorCode(C.SQLITE_READONLY_RECOVERY)
	SQLITE_READONLY_CANTLOCK       = ErrorCode(C.SQLITE_READONLY_CANTLOCK)
	SQLITE_READONLY_ROLLBACK       = ErrorCode(C.SQLITE_READONLY_ROLLBACK)
	SQLITE_READONLY_DBMOVED        = ErrorCode(C.SQLITE_READONLY_DBMOVED)
	SQLITE_READONLY_CANTINIT       = ErrorCode(C.SQLITE_READONLY_CANTINIT)
	SQLITE_READONLY_DIRECTORY      = ErrorCode(C.SQLITE_READONLY_DIRECTORY)
	SQLITE_ABORT_ROLLBACK          = ErrorCode(C.SQLITE_ABORT_ROLLBACK)
	SQLITE_CONSTRAINT_CHECK        = ErrorCode(C.SQLITE_CONSTRAINT_CHECK)
	SQLITE_CONSTRAINT_COMMITHOOK   = ErrorCode(C.SQLITE_CONSTRAINT_COMMITHOOK)
	SQLITE_CONSTRAINT_FOREIGNKEY   = ErrorCode(C.SQLITE_CONSTRAINT_FOREIGNKEY)
	SQLITE_CONSTRAINT_FUNCTION     = ErrorCode(C.SQLITE_CONSTRAINT_FUNCTION)
	SQLITE_CONSTRAINT_NOTNULL      = ErrorCode(C.SQLITE_CONSTRAINT_NOTNULL)
	SQLITE_CONSTRAINT_PRIMARYKEY   = ErrorCode(C.SQLITE_CONSTRAINT_PRIMARYKEY)
	SQLITE_CONSTRAINT_TRIGGER      = ErrorCode(C.SQLITE_CONSTRAINT_TRIGGER)
	SQLITE_CONSTRAINT_UNIQUE       = ErrorCode(C.SQLITE_CONSTRAINT_UNIQUE)
	SQLITE_CONSTRAINT_VTAB         = ErrorCode(C.SQLITE_CONSTRAINT_VTAB)
	SQLITE_CONSTRAINT_ROWID        = ErrorCode(C.SQLITE_CONSTRAINT_ROWID)
	SQLITE_NOTICE_RECOVER_WAL      = ErrorCode(C.SQLITE_NOTICE_RECOVER_WAL)
	SQLITE_NOTICE_RECOVER_ROLLBACK = ErrorCode(C.SQLITE_NOTICE_RECOVER_ROLLBACK)
	SQLITE_WARNING_AUTOINDEX       = ErrorCode(C.SQLITE_WARNING_AUTOINDEX)
	SQLITE_AUTH_USER               = ErrorCode(C.SQLITE_AUTH_USER)
)
View Source
const (
	LIMIT_LENGTH              = LimitId(C.SQLITE_LIMIT_LENGTH)
	LIMIT_SQL_LENGTH          = LimitId(C.SQLITE_LIMIT_SQL_LENGTH)
	LIMIT_COLUMN              = LimitId(C.SQLITE_LIMIT_COLUMN)
	LIMIT_EXPR_DEPTH          = LimitId(C.SQLITE_LIMIT_EXPR_DEPTH)
	LIMIT_COMPOUND_SELECT     = LimitId(C.SQLITE_LIMIT_COMPOUND_SELECT)
	LIMIT_VDBE_OP             = LimitId(C.SQLITE_LIMIT_VDBE_OP)
	LIMIT_FUNCTION_ARG        = LimitId(C.SQLITE_LIMIT_FUNCTION_ARG)
	LIMIT_ATTACHED            = LimitId(C.SQLITE_LIMIT_ATTACHED)
	LIMIT_LIKE_PATTERN_LENGTH = LimitId(C.SQLITE_LIMIT_LIKE_PATTERN_LENGTH)
	LIMIT_VARIABLE_NUMBER     = LimitId(C.SQLITE_LIMIT_VARIABLE_NUMBER)
	LIMIT_TRIGGER_DEPTH       = LimitId(C.SQLITE_LIMIT_TRIGGER_DEPTH)
	LIMIT_WORKER_THREADS      = LimitId(C.SQLITE_LIMIT_WORKER_THREADS)
)

noinspection GoSnakeCaseUsage

View Source
const (
	SQLITE_INTEGER = ColumnType(C.SQLITE_INTEGER)
	SQLITE_FLOAT   = ColumnType(C.SQLITE_FLOAT)
	SQLITE_TEXT    = ColumnType(C.SQLITE3_TEXT)
	SQLITE_BLOB    = ColumnType(C.SQLITE_BLOB)
	SQLITE_NULL    = ColumnType(C.SQLITE_NULL)
)
View Source
const (
	INDEX_CONSTRAINT_EQ        = ConstraintOp(C.SQLITE_INDEX_CONSTRAINT_EQ)
	INDEX_CONSTRAINT_GT        = ConstraintOp(C.SQLITE_INDEX_CONSTRAINT_GT)
	INDEX_CONSTRAINT_LE        = ConstraintOp(C.SQLITE_INDEX_CONSTRAINT_LE)
	INDEX_CONSTRAINT_LT        = ConstraintOp(C.SQLITE_INDEX_CONSTRAINT_LT)
	INDEX_CONSTRAINT_GE        = ConstraintOp(C.SQLITE_INDEX_CONSTRAINT_GE)
	INDEX_CONSTRAINT_MATCH     = ConstraintOp(C.SQLITE_INDEX_CONSTRAINT_MATCH)
	INDEX_CONSTRAINT_LIKE      = ConstraintOp(C.SQLITE_INDEX_CONSTRAINT_LIKE)
	INDEX_CONSTRAINT_GLOB      = ConstraintOp(C.SQLITE_INDEX_CONSTRAINT_GLOB)
	INDEX_CONSTRAINT_REGEXP    = ConstraintOp(C.SQLITE_INDEX_CONSTRAINT_REGEXP)
	INDEX_CONSTRAINT_NE        = ConstraintOp(C.SQLITE_INDEX_CONSTRAINT_NE)
	INDEX_CONSTRAINT_ISNOT     = ConstraintOp(C.SQLITE_INDEX_CONSTRAINT_ISNOT)
	INDEX_CONSTRAINT_ISNOTNULL = ConstraintOp(C.SQLITE_INDEX_CONSTRAINT_ISNOTNULL)
	INDEX_CONSTRAINT_ISNULL    = ConstraintOp(C.SQLITE_INDEX_CONSTRAINT_ISNULL)
	INDEX_CONSTRAINT_IS        = ConstraintOp(C.SQLITE_INDEX_CONSTRAINT_IS)
	INDEX_CONSTRAINT_FUNCTION  = ConstraintOp(C.SQLITE_INDEX_CONSTRAINT_FUNCTION)
)

noinspection GoSnakeCaseUsage

View Source
const (
	INDEX_SCAN_UNIQUE = ScanFlag(C.SQLITE_INDEX_SCAN_UNIQUE) // scan visits at most 1 row
)

noinspection GoSnakeCaseUsage

Variables

This section is empty.

Functions

func EponymousOnly

func EponymousOnly(b bool) func(*ModuleOptions)

EponymousOnly marks the module to be an eponymous-only module, prohibiting any "create virtual table" commands.

func Error

func Error(code ErrorCode, msg string) error

Error creates a new error with given error code and message

func Overloadable

func Overloadable(b bool) func(*ModuleOptions)

Overloadable marks the module as supporting function overloading. The module then also needs to implement Overloadable interface.

func ReadOnly

func ReadOnly(b bool) func(*ModuleOptions)

ReadOnly marks the module as being read-only, i.e. insert / update / delete commands are not supported.

func Register

func Register(fn ExtensionFunc)

Register registers the given fn under the default name. This function is kept for backwards compatibility reason.

func RegisterNamed

func RegisterNamed(name string, fn ExtensionFunc)

RegisterNamed registers the provided extension function under the given name

func Transaction

func Transaction(b bool) func(*ModuleOptions)

Transaction marks the module as supporting transactions. The module then also needs to implement Transactional interface.

func TwoPhaseCommit

func TwoPhaseCommit(b bool) func(*ModuleOptions)

TwoPhaseCommit marks the module as supporting two-phased commits.

Types

type AggregateContext

type AggregateContext struct {
	*Context
	// contains filtered or unexported fields
}

AggregateContext is an extension of context that allows us to store custom data related to an execution

func (*AggregateContext) Data

func (agg *AggregateContext) Data() interface{}

func (*AggregateContext) SetData

func (agg *AggregateContext) SetData(val interface{})

type AggregateFunction

type AggregateFunction interface {
	Function

	Step(*AggregateContext, ...Value)
	Final(*AggregateContext)
}

AggregateFunction represents a custom sql aggregate function

type ColumnType

type ColumnType int

ColumnType are codes for each of the SQLite fundamental data types: https://www.sqlite.org/c3ref/c_blob.html

func (ColumnType) String

func (t ColumnType) String() string

type Conn

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

Conn is an open connection to an sqlite3 database. Currently, it only provides a subset of methods available on an sqlite3 database handle. Namely, it only supports building a prepared statement (and operations on a prepared statement)

A Conn can only be used by goroutine at a time.

func (*Conn) AutoCommit

func (conn *Conn) AutoCommit() bool

AutoCommit returns the status of the auto_commit setting

func (*Conn) Exec

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

Exec executes an SQLite query without caching the underlying query. It is the spiritual equivalent of sqlite3_exec.

func (*Conn) LastInsertRowID

func (conn *Conn) LastInsertRowID() int64

LastInsertRowID reports the rowid of the most recently successful INSERT. see: https://www.sqlite.org/c3ref/last_insert_rowid.html

func (*Conn) OverloadFunction

func (conn *Conn) OverloadFunction(name string, args int) error

OverloadFunction registers a global version of a function with a particular name and number of parameters. If no such function exists before, a new function is created. The implementation of the new function always causes an exception to be thrown. So the new function is not good for anything by itself.

The only purpose of a function registered this way is to be a placeholder function that can be overloaded by a virtual table; as virtual tables can provide alternative implementations of functions using the xFindFunction(), but global versions of those functions must exist in order to be overloaded.

func (*Conn) Prepare

func (conn *Conn) Prepare(query string) (*Stmt, int, error)

Prepare prepares a query and returns an Stmt.

If the query has any unprocessed trailing bytes, its count is returned. see: https://www.sqlite.org/c3ref/prepare.html

type ConstraintOp

type ConstraintOp C.int

ConstraintOp op-code passed as input in BestIndex

type ConstraintUsage

type ConstraintUsage struct {
	ArgvIndex int
	Omit      bool
}

ConstraintUsage provides details about whether a constraint provided in IndexInfoInput was / can be utilised or not by the index.

type Context

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

Context is an *C.struct_sqlite3_context. It is used by custom functions to return result values. An SQLite context is in no way related to a Go context.Context.

adapted from https://github.com/crawshaw/sqlite/blob/ae45c9066f6e7b62bb7b491a0c7c9659f866ce7c/func.go

func (Context) ResultBlob

func (ctx Context) ResultBlob(v []byte)

func (Context) ResultError

func (ctx Context) ResultError(err error)

func (Context) ResultFloat

func (ctx Context) ResultFloat(v float64)

func (Context) ResultInt

func (ctx Context) ResultInt(v int)

func (Context) ResultInt64

func (ctx Context) ResultInt64(v int64)

func (Context) ResultNull

func (ctx Context) ResultNull()

func (Context) ResultPointer

func (ctx Context) ResultPointer(val interface{})

func (Context) ResultSubType

func (ctx Context) ResultSubType(v int)

func (Context) ResultText

func (ctx Context) ResultText(v string)

func (Context) ResultValue

func (ctx Context) ResultValue(v Value)

func (Context) ResultZeroBlob

func (ctx Context) ResultZeroBlob(n int64)

type ErrorCode

type ErrorCode int

ErrorCode is an SQLite extended error code.

The three SQLite result codes (SQLITE_OK, SQLITE_ROW, and SQLITE_DONE), are not errors so they should not be used in an Error.

func RegisterWith

func RegisterWith(conn UnderlyingConnection, fn ExtensionFunc) (ErrorCode, error)

RegisterWith registers the given extension with the provided connection object. The intended use-case is to provide support for statically linked extensions.

func (ErrorCode) Error

func (code ErrorCode) Error() string

func (ErrorCode) String

func (code ErrorCode) String() string

type ExtensionApi

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

ExtensionApi wraps the underlying sqlite_api_routines and allows Go code to hook into sqlite's extension facility.

func (*ExtensionApi) AutoCommit

func (ext *ExtensionApi) AutoCommit() bool

AutoCommit returns the status of the auto_commit setting

func (*ExtensionApi) Connection

func (ext *ExtensionApi) Connection() *Conn

Connection returns an instance of Conn which can be used to perform query on the database and more.

func (*ExtensionApi) CreateCollation

func (ext *ExtensionApi) CreateCollation(name string, cmp func(string, string) int) error

CreateCollation creates a new collation with the given name using the supplied comparison function. The comparison function must obey the rules defined at https://www.sqlite.org/c3ref/create_collation.html

func (*ExtensionApi) CreateFunction

func (ext *ExtensionApi) CreateFunction(name string, fn Function) error

CreateFunction creates a new custom sql function with the given name

func (*ExtensionApi) CreateModule

func (ext *ExtensionApi) CreateModule(name string, module Module, opts ...func(*ModuleOptions)) error

CreateModule creates a named virtual table module with the given name and module as implementation.

func (*ExtensionApi) Limit

func (ext *ExtensionApi) Limit(id LimitId) int

Limit queries for the limit with given identifier

func (*ExtensionApi) RegisterCommitHook

func (ext *ExtensionApi) RegisterCommitHook(fn func() int)

RegisterCommitHook sets the commit hook for a connection.

If the callback returns non-zero the transaction will become a rollback.

If there is an existing commit hook for this connection, it will be removed. If callback is nil the existing hook (if any) will be removed without creating a new one.

func (*ExtensionApi) RegisterRollbackHook

func (ext *ExtensionApi) RegisterRollbackHook(fn func() int)

RegisterRollbackHook sets the rollback hook for a connection.

If there is an existing rollback hook for this connection, it will be removed. If callback is nil the existing hook (if any) will be removed without creating a new one.

func (*ExtensionApi) SetLimit

func (ext *ExtensionApi) SetLimit(id LimitId, val int) int

SetLimit sets the limit for the given identifier

func (*ExtensionApi) Version

func (ext *ExtensionApi) Version() int

Version returns the sqlite3 library version number

type ExtensionFunc

type ExtensionFunc func(*ExtensionApi) (ErrorCode, error)

ExtensionFunc represents a sqlite3 extension function, invoked by sqlite3 core whenever the user registers the extension with the connection.

type Function

type Function interface {
	// Deterministic returns true if the function will always return
	// the same result given the same inputs within a single SQL statement
	Deterministic() bool

	// Args returns the number of arguments that this function accepts
	Args() int
}

Function represents a base "abstract" sql function. Function by itself is not valid. Implementers must pick one of the "sub-types" to implement.

type IndexConstraint

type IndexConstraint struct {
	ColumnIndex int          // column constrained .. -1 for rowid
	Op          ConstraintOp // constraint operator
	Usable      bool         // true if this constraint is usable
}

type IndexInfoInput

type IndexInfoInput struct {
	Constraints []*IndexConstraint
	OrderBy     []*OrderBy

	//  available only in SQLite 3.10.0 and later
	ColUsed *int64 // Mask of columns used by statement
	// contains filtered or unexported fields
}

IndexInfoInput is the input provided to the BestIndex method see: https://www.sqlite.org/vtab.html for more details

func (*IndexInfoInput) Collation

func (in *IndexInfoInput) Collation(pos int) string

Collation returns a string that is the name of the appropriate collation sequence to use for text comparisons on the constraint identified by pos.

type IndexInfoOutput

type IndexInfoOutput struct {
	ConstraintUsage []*ConstraintUsage
	IndexNumber     int     // identifier passed on to Cursor.Filter
	IndexString     string  // identifier passed on to Cursor.Filter
	OrderByConsumed bool    // true if output is already ordered
	EstimatedCost   float64 // estimated cost of using this index

	// used only in SQLite 3.8.2 and later
	EstimatedRows int64 // estimated number of rows returned

	// used only in SQLite 3.9.0 and later
	IdxFlags ScanFlag // mask of SQLITE_INDEX_SCAN_* flags
}

IndexInfoOutput is the output expected from BestIndex method

type LimitId

type LimitId int

LimitId is an integer id used to refer to sqlite's limits

type Module

type Module interface {
	// Connect connects to an existing instance and establishes a new connection to an existing virtual table.
	// It receives a slice of arguments passed to the module and a method to declare the virtual table's schema.
	// Connect must call declare or else the operation would fail and error would be returned to sqlite.
	//
	// If a module only declares a Connect method than it's an eponymous module (by default) and can either be
	// invoked directly or be used in a CREATE VIRTUAL TABLE statement. To make eponymous-only use EponymousOnly(true).
	// see: https://www.sqlite.org/vtab.html for details about normal, eponymous and eponymous-only modules.
	Connect(_ *Conn, args []string, declare func(string) error) (VirtualTable, error)
}

Module corresponds to an sqlite3_module and defines a module object used to implement a virtual table. The Module API is adapted to feel more Go-like and so, overall, is split into various sub-types all of which the implementer must provide in order to satisfy a sqlite_module interface.

type ModuleOptions

type ModuleOptions struct {
	EponymousOnly  bool // CREATE VIRTUAL TABLE is prohibited for eponymous-only virtual tables
	ReadOnly       bool // Insert / Update / Delete is not allowed on read-only tables
	Transactional  bool // Transactional must be set if the table implements the optional Transactional interface
	TwoPhaseCommit bool // TwoPhaseCommit must be set if the table supports two-phase commits (implies Transactional)
	Overloadable   bool // Overloadable must be set if the table supports overloading default functions / operations
}

ModuleOptions represents the various different module options that affect the module's registration process

type OrderBy

type OrderBy struct {
	ColumnIndex int  // column index
	Desc        bool // descending or ascending?
}

type OverloadableVirtualTable

type OverloadableVirtualTable interface {
	VirtualTable

	// FindFunction is called during sqlite3_prepare() to give the virtual table
	// implementation an opportunity to overload functions.
	// When a function uses a column from a virtual table as its first argument,
	// this method is called to see if the virtual table would like to overload the function.
	// The method receives the SQL function name and it's argument count as arguments.
	// Please refer to official SQLite documentation to find more about the acceptable return values.
	FindFunction(string, int) (int, func(*Context, ...Value))
}

OverloadableVirtualTable is an optional interface the VirtualTable implementations can implement to allow them an opportunity to overload functions, replacing them with optimised implementations. For more details and implementation notes, please refer to official documentation at https://www.sqlite.org/vtab.html#the_xfindfunction_method

type ScalarFunction

type ScalarFunction interface {
	Function

	Apply(*Context, ...Value)
}

ScalarFunction represents a custom sql scalar function

type ScanFlag

type ScanFlag int

ScanFlags masking bits used by virtual table implementations to set the IndexInfoOutput.IdxFlags field

type StatefulModule

type StatefulModule interface {
	Module

	// Create creates a new instance of a virtual table in response to a CREATE VIRTUAL TABLE statement.
	// It receives a slice of arguments passed to the module and a method to declare the virtual table's schema.
	// Create must call declare or else the operation would fail and error would be returned to sqlite.
	Create(_ *Conn, args []string, declare func(string) error) (VirtualTable, error)
}

StatefulModule is one which requires prior state initialization before one can connect to it.

type Stmt

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

Stmt is an SQLite3 prepared statement.

A Stmt is attached to a particular Conn (and that Conn can only be used by a single goroutine).

When a Stmt is no longer needed it should be cleaned up by calling the Finalize method.

func (*Stmt) BindBool

func (stmt *Stmt) BindBool(param int, value bool)

BindBool binds value (as an integer 0 or 1) to a numbered stmt parameter.

func (*Stmt) BindBytes

func (stmt *Stmt) BindBytes(param int, value []byte)

BindBytes binds value to a numbered stmt parameter. In-memory copies of value are made using this interface.

func (*Stmt) BindFloat

func (stmt *Stmt) BindFloat(param int, value float64)

BindFloat binds value to a numbered stmt parameter.

func (*Stmt) BindInt64

func (stmt *Stmt) BindInt64(param int, value int64)

BindInt64 binds value to a numbered stmt parameter.

func (*Stmt) BindName

func (stmt *Stmt) BindName(param int) string

BindName returns the name assigned to a particular parameter in the query.

see: https://www.sqlite.org/c3ref/bind_parameter_name.html

func (*Stmt) BindNull

func (stmt *Stmt) BindNull(param int)

BindNull binds an SQL NULL value to a numbered stmt parameter.

func (*Stmt) BindParamCount

func (stmt *Stmt) BindParamCount() int

BindParamCount reports the number of parameters in stmt.

see: https://www.sqlite.org/c3ref/bind_parameter_count.html

func (*Stmt) BindPointer

func (stmt *Stmt) BindPointer(param int, arg interface{})

BindPointer binds any arbitrary Go value with the parameter. The value can later be retrieved by custom functions or callbacks, casted back into a Go type, and used in golang's environment.

func (*Stmt) BindText

func (stmt *Stmt) BindText(param int, value string)

BindText binds value to a numbered stmt parameter.

func (*Stmt) BindValue

func (stmt *Stmt) BindValue(param int, value Value)

BindValue binds an sqlite_value object at given index

func (*Stmt) BindZeroBlob

func (stmt *Stmt) BindZeroBlob(param int, len int64)

BindNull binds a blob of zeros of length len to a numbered stmt parameter.

func (*Stmt) ClearBindings

func (stmt *Stmt) ClearBindings() error

ClearBindings clears all bound parameter values on a statement.

see: https://www.sqlite.org/c3ref/clear_bindings.html

func (*Stmt) ColumnBytes

func (stmt *Stmt) ColumnBytes(col int, buf []byte) int

ColumnBytes reads a query result into buf. It reports the number of bytes read.

func (*Stmt) ColumnCount

func (stmt *Stmt) ColumnCount() int

ColumnCount returns the number of columns in the result set returned by the prepared statement.

see: https://sqlite.org/c3ref/column_count.html

func (*Stmt) ColumnDatabaseName

func (stmt *Stmt) ColumnDatabaseName(col int) string

func (*Stmt) ColumnFloat

func (stmt *Stmt) ColumnFloat(col int) float64

ColumnFloat returns a query result as a float64.

func (*Stmt) ColumnIndex

func (stmt *Stmt) ColumnIndex(colName string) int

ColumnIndex returns the index of the column with the given name.

If there is no column with the given name ColumnIndex returns -1.

func (*Stmt) ColumnInt

func (stmt *Stmt) ColumnInt(col int) int

ColumnInt returns a query result value as an int.

Note: this method calls sqlite3_column_int64 and then converts the resulting 64-bits to an int.

func (*Stmt) ColumnInt32

func (stmt *Stmt) ColumnInt32(col int) int32

ColumnInt32 returns a query result value as an int32.

func (*Stmt) ColumnInt64

func (stmt *Stmt) ColumnInt64(col int) int64

ColumnInt64 returns a query result value as an int64.

func (*Stmt) ColumnLen

func (stmt *Stmt) ColumnLen(col int) int

ColumnLen returns the number of bytes in a query result.

func (*Stmt) ColumnName

func (stmt *Stmt) ColumnName(col int) string

ColumnName returns the name assigned to a particular column in the result set of a SELECT statement.

see: https://sqlite.org/c3ref/column_name.html

func (*Stmt) ColumnOriginName

func (stmt *Stmt) ColumnOriginName(col int) string

func (*Stmt) ColumnReader

func (stmt *Stmt) ColumnReader(col int) *bytes.Reader

ColumnReader creates a byte reader for a query result column.

The reader directly references C-managed memory that stops being valid as soon as the statement row resets.

func (*Stmt) ColumnTableName

func (stmt *Stmt) ColumnTableName(col int) string

func (*Stmt) ColumnText

func (stmt *Stmt) ColumnText(col int) string

ColumnText returns a query result as a string.

func (*Stmt) ColumnType

func (stmt *Stmt) ColumnType(col int) ColumnType

ColumnType returns the datatype code for the initial data type of the result column.

func (*Stmt) ColumnValue

func (stmt *Stmt) ColumnValue(col int) Value

ColumnValue returns a query result as an sqlite_value.

func (*Stmt) DataCount

func (stmt *Stmt) DataCount() int

DataCount returns the number of columns in the current row of the result set of prepared statement.

see: https://sqlite.org/c3ref/data_count.html

func (*Stmt) Finalize

func (stmt *Stmt) Finalize() error

Finalize deletes a prepared statement.

Be sure to always call Finalize when done with a statement created using Prepare.

Do not call Finalize on a prepared statement that you intend to prepare again in the future.

see: https://www.sqlite.org/c3ref/finalize.html

func (*Stmt) GetBytes

func (stmt *Stmt) GetBytes(colName string, buf []byte) int

GetBytes reads a query result for colName into buf. It reports the number of bytes read.

func (*Stmt) GetFloat

func (stmt *Stmt) GetFloat(colName string) float64

GetFloat returns a query result value for colName as a float64.

func (*Stmt) GetInt64

func (stmt *Stmt) GetInt64(colName string) int64

GetInt64 returns a query result value for colName as an int64.

func (*Stmt) GetLen

func (stmt *Stmt) GetLen(colName string) int

GetLen returns the number of bytes in a query result for colName.

func (*Stmt) GetReader

func (stmt *Stmt) GetReader(colName string) *bytes.Reader

GetReader creates a byte reader for colName.

The reader directly references C-managed memory that stops being valid as soon as the statement row resets.

func (*Stmt) GetText

func (stmt *Stmt) GetText(colName string) string

GetText returns a query result value for colName as a string.

func (*Stmt) GetValue

func (stmt *Stmt) GetValue(colName string) Value

GetValue returns a query result value for colName as an sqlite_value.

func (*Stmt) Readonly

func (stmt *Stmt) Readonly() bool

Readonly returns true if this statement is readonly and makes no direct changes to the content of the database file. See: https://www.sqlite.org/c3ref/stmt_readonly.html

func (*Stmt) Reset

func (stmt *Stmt) Reset() error

Reset resets a prepared statement so it can be executed again.

Note that any parameter values bound to the statement are retained. To clear bound values, call ClearBindings.

see: https://www.sqlite.org/c3ref/reset.html

func (*Stmt) SetBool

func (stmt *Stmt) SetBool(param string, value bool)

SetBool binds a value (as a 0 or 1) to a parameter using a column name.

func (*Stmt) SetBytes

func (stmt *Stmt) SetBytes(param string, value []byte)

SetBytes binds bytes to a parameter using a column name. An invalid parameter name will cause the call to Step to return an error.

func (*Stmt) SetFloat

func (stmt *Stmt) SetFloat(param string, value float64)

SetFloat binds a float64 to a parameter using a column name. An invalid parameter name will cause the call to Step to return an error.

func (*Stmt) SetInt64

func (stmt *Stmt) SetInt64(param string, value int64)

SetInt64 binds an int64 to a parameter using a column name.

func (*Stmt) SetNull

func (stmt *Stmt) SetNull(param string)

SetNull binds a null to a parameter using a column name. An invalid parameter name will cause the call to Step to return an error.

func (*Stmt) SetPointer

func (stmt *Stmt) SetPointer(param string, arg interface{})

SetPointer binds a golang value to a parameter using a column name.

func (*Stmt) SetText

func (stmt *Stmt) SetText(param string, value string)

SetText binds text to a parameter using a column name. An invalid parameter name will cause the call to Step to return an error.

func (*Stmt) SetValue

func (stmt *Stmt) SetValue(param string, value Value)

SetValue binds an sqlite3_value to a parameter using a column name. An invalid parameter name will cause the call to Step to return an error.

func (*Stmt) SetZeroBlob

func (stmt *Stmt) SetZeroBlob(param string, len int64)

SetZeroBlob binds a zero blob of length len to a parameter using a column name. An invalid parameter name will cause the call to Step to return an error.

func (*Stmt) Step

func (stmt *Stmt) Step() (rowReturned bool, err error)

Step moves through the statement cursor using sqlite3_step.

If a row of data is available, rowReturned is reported as true. If the statement has reached the end of the available data then rowReturned is false. Thus the status codes SQLITE_ROW and SQLITE_DONE are reported by the rowReturned bool, and all other non-OK status codes are reported as an error.

If an error value is returned, then the statement has been reset.

https://www.sqlite.org/c3ref/step.html

Shared cache

If Shared Cache mode is enabled, this Step method uses sqlite3_unlock_notify to handle any SQLITE_LOCKED errors.

Without the shared cache, SQLite will block for several seconds while trying to acquire the write lock. With the shared cache, it returns SQLITE_LOCKED immediately if the write lock is held by another connection in this process. Dealing with this correctly makes for an unpleasant programming experience, so this package does it automatically by blocking Step until the write lock is relinquished.

This means Step can block for a very long time.

For far more details, see: http://www.sqlite.org/unlock_notify.html

type Transactional

type Transactional interface {
	VirtualTable

	// Begin begins a transaction on a virtual table.
	// This method is always followed by one call to either the Commit or Rollback method.
	// Virtual table transactions do not nest, so the Begin method will not be invoked more
	// than once on a single virtual table without an intervening call to either Commit or Rollback.
	Begin() error

	// Commit is invoked to commit the current virtual table transaction.
	Commit() error

	// Rollback is invoked to rollback the current virtual table transaction.
	Rollback() error
}

Transactional is an optional interface that VirtualTable implementations can implement to enable support for atomic transactions.

type TwoPhaseCommitter

type TwoPhaseCommitter interface {
	Transactional

	// Sync signals the start of a two-phase commit on a virtual table.
	// It is only invoked after call to the Begin method and prior to an Commit or Rollback.
	// In order to implement two-phase commit, the Sync method on all virtual tables is invoked
	// prior to invoking the Commit method on any virtual table. If any of the Sync methods fail,
	// the entire transaction is rolled back.
	Sync() error
}

TwoPhaseCommitter is an optional interface that VirtualTable implementations (which also implements Transactional) can implement to enable support for two-phased commits.

type UnderlyingConnection

type UnderlyingConnection *C.struct_sqlite3

UnderlyingConnection represents a handle to an open sqlite3 database connection object.

type Value

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

Value is an *C.sqlite3_value. Value represent all values that can be stored in a database table. It is used to extract column values from sql queries.

adapted from https://github.com/crawshaw/sqlite/blob/ae45c9066f6e7b62bb7b491a0c7c9659f866ce7c/func.go

func (Value) Blob

func (v Value) Blob() []byte

func (Value) Float

func (v Value) Float() float64

func (Value) Int

func (v Value) Int() int

func (Value) Int64

func (v Value) Int64() int64

func (Value) IsNil

func (v Value) IsNil() bool

func (Value) Len

func (v Value) Len() int

func (Value) NoChange

func (v Value) NoChange() bool

func (Value) Pointer

func (v Value) Pointer() interface{}

func (Value) SubType

func (v Value) SubType() int

func (Value) Text

func (v Value) Text() string

func (Value) Type

func (v Value) Type() ColumnType

type VirtualCursor

type VirtualCursor interface {
	// Filter begins a search of a virtual table.
	// It receives the IndexNumber and IndexString returned by BestIndex method previously.
	// The BestIndex function may have also requested the values of certain expressions using
	// the ConstraintUsage[].ArgvIndex values of the IndexInfoOutput. Those values are passed
	// to Filter as a list of Value objects.
	Filter(int, string, ...Value) error

	// Next advances a virtual table cursor to the next row of a result set initiated by Filter.
	// If the cursor is already pointing at the last row when this routine is called,
	// then the cursor no longer points to valid data and a subsequent call to the Eof method must return true.
	// If the cursor is successfully advanced to another row of content, then subsequent calls to xEof must return false.
	Next() error

	// Rowid returns the rowid of row that the virtual table cursor is currently pointing at.
	Rowid() (int64, error)

	// Column is invoked by SQLite core in order to find the value for the N-th column of the current row.
	// N is zero-based so the first column is numbered 0. Column may return its result back using the various ResultX
	// methods defined on the Context argument. If the implementation calls none of those functions,
	// then the value of the column defaults to an SQL NULL.
	Column(*VirtualTableContext, int) error

	// Eof returns false if the specified cursor currently points to a valid row of data,
	// or true otherwise. This method is called by the SQL engine immediately after each Filter and Next invocation.
	Eof() bool

	// Close closes a cursor previously opened by Open.
	// The SQLite core will always call Close once for each cursor opened using Open.
	Close() error
}

VirtualCursor corresponds to an sqlite3_vtab_cursor. The cursor represents a pointer to a specific row of a virtual table

type VirtualTable

type VirtualTable interface {
	// BestIndex is used to determine whether an index is available and can be used to optimise query for the table.
	// SQLite uses the BestIndex method of a virtual table module to determine the best way to access the virtual table.
	BestIndex(*IndexInfoInput) (*IndexInfoOutput, error)

	// Open creates a new cursor used for accessing (read and/or writing) a virtual table.
	// When initially opened, the cursor is in an undefined state. The SQLite core will invoke the
	// Filter method on the cursor prior to any attempt to position or read from the cursor.
	// A virtual table implementation must be able to support an arbitrary number of simultaneously open cursors.
	Open() (VirtualCursor, error)

	// Disconnect releases a connection to a virtual table.
	// Only the virtual table connection is destroyed.
	// The virtual table is not destroyed and any backing store associated with the virtual table persists.
	Disconnect() error

	// Destroy releases a connection to a virtual table, just like the Disconnect method,
	// and it also destroys the underlying table implementation.
	Destroy() error
}

VirtualTable corresponds to an sqlite3_vtab and defines a virtual table object used to implement a virtual table. By default implementations of this interface are considered read-only. Implement WriteableVirtualTable and use ReadOnly(false) option to enable read-write support.

type VirtualTableContext

type VirtualTableContext struct{ *Context }

VirtualTableContext is an extension of sqlite.Context that allows us to access some specialised interfaces only available when dealing with virtual tables.

func (*VirtualTableContext) NoChange

func (ctx *VirtualTableContext) NoChange() bool

NoChange returns true if the column is being fetched as part of an UPDATE operation during which the column value will not change. The virtual table implementation can use this hint as permission to substitute a return value that is less expensive to compute and that the corresponding Update() method understands as a "no-change" value.

type WindowFunction

type WindowFunction interface {
	AggregateFunction

	Value(*AggregateContext)
	Inverse(*AggregateContext, ...Value)
}

WindowFunction represents a custom sql window function

type WriteableVirtualTable

type WriteableVirtualTable interface {
	VirtualTable

	// Insert inserts a new row reading column values from the passed in list of values.
	// In a rowid virtual table, the implementation must choose a rowid for the newly inserted row.
	// For a WITHOUT ROWID virtual table, implementation should take the PRIMARY KEY value from the appropriate column.
	//
	// When doing an Insert on a virtual table that uses ROWID, implementations must return the rowid of
	// the newly inserted row; this will become the value returned by the sqlite3_last_insert_rowid() function.
	// Returning a value for rowid in a WITHOUT ROWID table is a harmless no-op.
	Insert(...Value) (int64, error)

	// Update updates an existing row identified by the rowid / primary-key given as the first argument.
	Update(Value, ...Value) error

	// Replace replaces an existing row identified by the rowid / primary-key given as old
	// and replacing it with the new id. The update might also include a list of other columns too.
	// This will occur when an SQL statement updates a rowid, as in the statement:
	//   UPDATE table SET rowid=rowid+1 WHERE ...;
	Replace(old, new Value, _ ...Value) error

	// Delete deletes the row identified the rowid / primary-key in the given value.
	Delete(Value) error
}

WriteableVirtualTable is one that supports INSERT, UPDATE and/or DELETE operations.

There might be one or more cursor objects open and in use on the virtual table instance and perhaps even on the row of the virtual table when the write methods are invoked. The implementation must be prepared for attempts to delete or modify rows of the table out from other existing cursors. If the virtual table cannot accommodate such changes, the methods must return an error code.

Directories

Path Synopsis
_examples
csv
sum
internal
testing/sqlite
Package sqlite provides a golang package that calls to sqlite3_auto_extension to automatically load the extension with every new connection.
Package sqlite provides a golang package that calls to sqlite3_auto_extension to automatically load the extension with every new connection.

Jump to

Keyboard shortcuts

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