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

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.

Source Files

View all Source files

Directories

Path Synopsis
_examples
compare
csv
series
subtype
sum
upper
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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.