csqlite

package
v0.1.7 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source
const (
	OK   = 0
	Row  = 100
	Done = 101

	OpenReadOnly     = 0x00000001
	OpenReadWrite    = 0x00000002
	OpenCreate       = 0x00000004
	OpenURI          = 0x00000040
	OpenMemory       = 0x00000080
	OpenNoMutex      = 0x00008000
	OpenFullMutex    = 0x00010000
	OpenSharedCache  = 0x00020000
	OpenPrivateCache = 0x00040000
	OpenExResCode    = 0x02000000

	TypeInteger = 1
	TypeFloat   = 2
	TypeText    = 3
	TypeBlob    = 4
	TypeNull    = 5
)

Result codes and flags of sqlite3.h.

View Source
const (
	FuncDeterministic = 0x000000800
	FuncDirectOnly    = 0x000080000
	FuncInnocuous     = 0x000200000
)

Flags of CreateFunction (sqlite3.h).

View Source
const (
	CheckpointPassive  = 0
	CheckpointFull     = 1
	CheckpointRestart  = 2
	CheckpointTruncate = 3
)

The modes of Checkpoint (SQLITE_CHECKPOINT_*).

View Source
const (
	// ModEponymousOnly: the module is only used by its name, as a function
	// whose arguments are its hidden columns. CREATE VIRTUAL TABLE fails.
	ModEponymousOnly = 1 << iota
	// ModDirectOnly: its tables may not be used by triggers and views.
	ModDirectOnly
	// ModInnocuous: its tables are safe wherever SQL comes from.
	ModInnocuous
	// ModWritable: its tables take INSERT, UPDATE and DELETE when they are
	// VUpdaters, and those statements never merge. Not with ModEponymousOnly.
	ModWritable
)

Flags of CreateModule.

View Source
const (
	IndexEQ        = 2
	IndexGT        = 4
	IndexLE        = 8
	IndexLT        = 16
	IndexGE        = 32
	IndexMatch     = 64
	IndexLike      = 65
	IndexGlob      = 66
	IndexRegexp    = 67
	IndexNE        = 68
	IndexIsNot     = 69
	IndexIsNotNull = 70
	IndexIsNull    = 71
	IndexIs        = 72
	IndexLimit     = 73
	IndexOffset    = 74
	IndexFunction  = 150
)

The operators of IndexConstraint (SQLITE_INDEX_CONSTRAINT_*).

View Source
const FuncBorrowBlobs = 1 << 30

FuncBorrowBlobs is a flag of CreateFunction that is not SQLite's: the function gets its BLOB arguments in place, in SQLite's memory, without a copy. They hold until the function returns, and it must not keep them. Only functions of this module use it (ext/vec), where copying two vectors per row costs more than the work.

Variables

View Source
var ErrBroken = errors.New("sqlite: connection is broken")

ErrBroken is the error of a call on a connection a host callback panicked under. Test for it with errors.Is.

View Source
var ErrCollationPanic = errors.New("panic in a Go collation")

ErrCollationPanic is under the error of a statement in which a Go collation panicked.

View Source
var ErrConstraint = errors.New("no usable plan for the virtual table")

ErrConstraint is what BestIndex returns for a plan that cannot work.

View Source
var ErrGuarded = errors.New("sqlite: the replicator runs the checkpoints of this database")

ErrGuarded is under the error of a PRAGMA refused on a connection to a replicated database (SetGuard).

View Source
var ErrRolledBack = errors.New("sqlite: the transaction of the statement was rolled back while it ran: what it wrote is gone")

ErrRolledBack is the error of a statement that wrote, at its end, when SQLite rolled back its transaction while it ran: another statement of the connection failed in a way that ends the transaction (out of memory, an I/O error, a full disk, a panic in a Go collation), or ROLLBACK ran.

Functions

func AdjustTree

func AdjustTree(a0 uintptr, a1 uintptr, a2 uintptr, a3 uintptr) uintptr

func ChooseLeaf

func ChooseLeaf(a0 uintptr, a1 uintptr, a2 uintptr, a3 uintptr, a4 uintptr) uintptr

func LibVersion

func LibVersion() (string, error)

LibVersion is the version of the SQLite in the engine.

func SetAllocFault added in v0.1.5

func SetAllocFault(f func(n uintptr) bool)

SetAllocFault has every malloc and realloc of the C ask f first, with the bytes asked for: when f says true the C gets no memory, as when the system has none to give. It is for tests that check what SQLite and the driver do when memory runs out. f is called from every goroutine that allocates. nil turns it off.

func SortByDimension

func SortByDimension(a0 uintptr, a1 uintptr, a2 uintptr, a3 uintptr, a4 uintptr, a5 uintptr, a6 uintptr)

Types

type Agg

type Agg interface {
	Step(args []driver.Value) error
	Final() (driver.Value, error)
}

Agg is the state of one group of an aggregate function written in Go: Step for each row of the group, then Final once. Step's arguments are copies, like a Func's.

type Conn

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

Conn is a connection to a database.

func Open

func Open(name string, flags int, vfs string) (*Conn, error)

Open opens a connection. It does not take OpenFullMutex: a connection has one shadow stack, so two goroutines cannot run on it at once, and a mutex of SQLite could not tell them apart.

func (*Conn) Attached added in v0.1.5

func (c *Conn) Attached() bool

Attached says the connection has a database attached.

func (*Conn) AutoCommit

func (c *Conn) AutoCommit() bool

AutoCommit says whether no transaction is open.

func (*Conn) Broken

func (c *Conn) Broken() bool

Broken says a host callback panicked under the connection. It is safe to call from any goroutine.

func (*Conn) BusyTimeout

func (c *Conn) BusyTimeout(ms int) error

BusyTimeout sets how long a statement waits for a lock.

func (*Conn) BusyTimeoutNow added in v0.1.5

func (c *Conn) BusyTimeoutNow() (ms int, ok bool)

BusyTimeoutNow is the busy timeout of the connection in milliseconds, 0 for none, as PRAGMA busy_timeout reads it. ok is false when the connection is broken. It runs no statement, so it also tells after a statement that failed, when SQLite may refuse another: an interrupt stays while a query of the connection is open.

func (*Conn) ChangedItself added in v0.1.4

func (c *Conn) ChangedItself() bool

ChangedItself says a statement that changes the connection was prepared on it, run or not.

func (*Conn) Changes

func (c *Conn) Changes() int64

Changes is the number of rows the last statement changed.

func (*Conn) Checkpoint added in v0.1.3

func (c *Conn) Checkpoint(mode int) (log, ckpt int, err error)

Checkpoint checkpoints the main database. log is the number of frames in the WAL, ckpt the number of them now in the database file: -1 each when the database is not in WAL mode.

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection. Its statements must be finalized first: with one open, Close returns SQLITE_BUSY and the connection stays open and usable, since SQLite would otherwise keep a half-closed connection that runs on a shadow stack already given back. A broken connection runs no C: Close frees its stack and returns the error that says so.

func (*Conn) CreateAggregate

func (c *Conn) CreateAggregate(name string, nArg int, flags int, newAgg func() Agg) error

CreateAggregate makes an aggregate function name: newAgg makes the state of each group.

func (*Conn) CreateCollation

func (c *Conn) CreateCollation(name string, cmp func(a, b string) int) error

CreateCollation makes cmp the collation name. cmp returns a negative number, 0 or a positive number as a sorts before, with or after b.

func (*Conn) CreateFunction

func (c *Conn) CreateFunction(name string, nArg int, flags int, f Func) error

CreateFunction makes f the SQL function name of nArg arguments (-1 for any number) on the connection, in place of one of the same name and nArg.

func (*Conn) CreateModule added in v0.1.3

func (c *Conn) CreateModule(name string, m Module, flags int) error

CreateModule makes m the virtual table module name on the connection.

func (*Conn) CreateWindow added in v0.1.3

func (c *Conn) CreateWindow(name string, nArg int, flags int, newWin func() WindowAgg) error

CreateWindow makes an aggregate window function name: newWin makes the state of each group or partition.

func (*Conn) DeferredFKs

func (c *Conn) DeferredFKs() bool

DeferredFKs says foreign key constraints of the transaction are not resolved yet (SQLITE_DBSTATUS_DEFERRED_FKS).

func (*Conn) Exec

func (c *Conn) Exec(sql string) error

Exec runs one or more statements that return no rows.

func (*Conn) Filename

func (c *Conn) Filename(schema string) string

Filename is the absolute name of the file of database schema ("main"), or "" for a memory or temporary database.

func (*Conn) Filenames added in v0.1.5

func (c *Conn) Filenames() []string

Filenames are the absolute names of the files of the databases of the connection, main and attached, without memory and temporary ones.

func (*Conn) GiveAutoCheckpoint added in v0.1.5

func (c *Conn) GiveAutoCheckpoint() bool

GiveAutoCheckpoint gives the automatic checkpoints of the connection back to SQLite, with the wal_autocheckpoint they were taken with. It says whether they were taken.

func (*Conn) InTx added in v0.1.4

func (c *Conn) InTx() bool

InTx says SQLite has a transaction open on the connection, a read one too: in autocommit, a query not done holds one, with the snapshot it read.

func (*Conn) Interrupt

func (c *Conn) Interrupt() error

Interrupt stops the statement running on the connection, from any goroutine. The statement returns SQLITE_INTERRUPT.

func (*Conn) JustChanged added in v0.1.4

func (c *Conn) JustChanged() bool

JustChanged says the last Prepare was of a statement that changes the connection, even one that failed after SQLite applied it (PRAGMA busy_timeout = 0 junk).

func (*Conn) LastInsertRowID

func (c *Conn) LastInsertRowID() int64

LastInsertRowID is the rowid of the last row inserted.

func (*Conn) PageCount added in v0.1.3

func (c *Conn) PageCount() (uint32, error)

PageCount is the size of the main database in pages, as the open read transaction sees it.

func (*Conn) Prepare

func (c *Conn) Prepare(sql string) (s *Stmt, tail string, err error)

Prepare compiles the first statement of sql. tail is the rest of sql. A nil statement with no error is sql with no statement in it.

func (*Conn) RanEffects added in v0.1.5

func (c *Conn) RanEffects() bool

RanEffects reports whether a Go function that may have side effects (one not marked FuncInnocuous) ran on the connection since SetMerging(true).

func (*Conn) ReadOnly

func (c *Conn) ReadOnly() bool

ReadOnly says the main database is open read-only.

func (*Conn) ReadPage added in v0.1.3

func (c *Conn) ReadPage(pgno uint32, buf []byte) error

ReadPage reads page pgno of the main database, as the open read transaction sees it, into buf, which is one page long. The lock page cannot be read.

func (*Conn) SetGuard added in v0.1.3

func (c *Conn) SetGuard(on bool)

SetGuard makes the connection refuse the PRAGMAs that would take the checkpoints of its main database from the replicator: wal_checkpoint, wal_autocheckpoint, journal_mode other than WAL and locking_mode other than NORMAL.

func (*Conn) SetLastInsertRowID

func (c *Conn) SetLastInsertRowID(id int64)

SetLastInsertRowID sets what LastInsertRowID and last_insert_rowid() give.

func (*Conn) SetMerging added in v0.1.3

func (c *Conn) SetMerging(on bool) (wasRefused bool)

SetMerging says whether the connection runs statements of other connections' callers (group commit). While it does, a statement that SQLite prepares again after a change of the schema and that is no longer mergeable fails before it does anything. Turned off, SetMerging reports whether that happened since it was turned on: the statement must run on its caller's connection, and Reclassify sorts it again.

func (*Conn) Spent added in v0.1.5

func (c *Conn) Spent() bool

Spent says SQLite ran out of memory, failed to read or write a file or found the disk full on the connection. These are the errors that make SQLite roll a transaction back at once, also when the statement that failed is one an extension runs inside a statement of the caller, which is still running. FTS5 then goes on with what it had read before the rollback and keeps it for its next write: the count of rows it failed to read, as zero. SQLite tells no one that this happened, so a connection that gave one of these errors is not to start anything more.

A checkpoint the driver runs itself (Checkpoint) does not count: it runs no statement, so no extension is in the middle of one.

func (*Conn) TakeAutoCheckpoint added in v0.1.5

func (c *Conn) TakeAutoCheckpoint() (n int, ok bool)

TakeAutoCheckpoint takes the automatic checkpoints of the connection from SQLite, which runs none of them from then on: the caller does. n is the wal_autocheckpoint the connection had, 0 for none. ok is false when they were taken already. PRAGMA wal_autocheckpoint=N gives them back to SQLite with N, as soon as it is prepared, and a call after it takes them again and tells N. PRAGMA wal_autocheckpoint reads the same either way.

func (*Conn) VirtualTablesInTx

func (c *Conn) VirtualTablesInTx() bool

VirtualTablesInTx says virtual tables take part in the open transaction: one was written since it began.

func (*Conn) WALHeader added in v0.1.3

func (c *Conn) WALHeader() (WALHeader, error)

WALHeader is the WAL header the open read transaction of the connection reads.

func (*Conn) WALNow added in v0.1.5

func (c *Conn) WALNow() (frames, salt uint32, ok bool)

WALNow is the WAL of the main database as it is now: its length in frames, and a number that changes each time the WAL starts over. ok is false when the connection has not read that WAL yet, has none, or is broken.

It needs no transaction, and it is not what the connection last saw: a connection that has not touched the main database for a while, as one that writes only its temporary tables, still gets the WAL of now.

type Error

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

Error is a result code of SQLite with its message.

func NewError added in v0.1.5

func NewError(code int, msg string, cause error) *Error

NewError is an error of the extended result code code with the message msg, and cause under it (nil for none).

func (*Error) Code

func (e *Error) Code() int

Code is the primary result code, as SQLITE_CONSTRAINT.

func (*Error) Error

func (e *Error) Error() string

func (*Error) ExtendedCode added in v0.1.5

func (e *Error) ExtendedCode() int

ExtendedCode is the extended result code, as SQLITE_CONSTRAINT_UNIQUE. For an error that has no extended code it is the primary code.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap is what is under the error: the error that made it, or nil.

type Func

type Func func(args []driver.Value) (driver.Value, error)

Func is a SQL function written in Go. Its arguments are copies, of the types int64, float64, string, []byte and nil. It returns one of those, an int or a bool, or an error that becomes the error of the statement. A panic in it is recovered and becomes the error of the statement too.

type IndexConstraint added in v0.1.3

type IndexConstraint struct {
	Column int // -1 for the rowid
	Op     int
	Usable bool
}

IndexConstraint is a term of the WHERE clause on one column. A term that is not usable may not get an ArgvIndex.

type IndexInfo added in v0.1.3

type IndexInfo struct {
	Constraints []IndexConstraint
	OrderBy     []IndexOrderBy
	ColUsed     uint64 // bit i: column i is used, bit 63: a column from 63 up is

	Usage           []IndexUsage // as long as Constraints
	IdxNum          int
	IdxStr          string
	OrderByConsumed bool
	EstimatedCost   float64
	EstimatedRows   int64
	Unique          bool // at most one row (SQLITE_INDEX_SCAN_UNIQUE)
}

IndexInfo is the question of xBestIndex and its answer.

type IndexOrderBy added in v0.1.3

type IndexOrderBy struct {
	Column int
	Desc   bool
}

IndexOrderBy is a term of the ORDER BY clause.

type IndexUsage added in v0.1.3

type IndexUsage struct {
	ArgvIndex int
	Omit      bool
}

IndexUsage is what BestIndex says of a constraint: ArgvIndex > 0 gives its value to Filter at args[ArgvIndex-1], and Omit says SQLite need not check it again.

type Module added in v0.1.3

type Module func(args []string) (VTable, error)

Module makes the table of a virtual table module for a connection: for CREATE VIRTUAL TABLE t USING name(args...), when a connection first uses such a table, and for the module's name used as a table. args are the arguments after the name, as SQL wrote them.

type Stmt

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

Stmt is a prepared statement.

func (*Stmt) BindBlob

func (s *Stmt) BindBlob(i int, v []byte) error

func (*Stmt) BindDouble

func (s *Stmt) BindDouble(i int, v float64) error

func (*Stmt) BindInt64

func (s *Stmt) BindInt64(i int, v int64) error

func (*Stmt) BindNull

func (s *Stmt) BindNull(i int) error

func (*Stmt) BindText

func (s *Stmt) BindText(i int, v string) error

func (*Stmt) ChangesConn

func (s *Stmt) ChangesConn() bool

ChangesConn says the statement changes the connection itself: a PRAGMA that sets something, ATTACH, DETACH, or a temporary table, index, view or trigger.

func (*Stmt) ClearBindings

func (s *Stmt) ClearBindings() error

ClearBindings sets every parameter to NULL.

func (*Stmt) ColumnBlob

func (s *Stmt) ColumnBlob(i int) ([]byte, error)

ColumnBlob is the bytes of column i, copied: nil for NULL and for a blob of no bytes. It fails when SQLite has no memory for it.

func (*Stmt) ColumnCount

func (s *Stmt) ColumnCount() int

ColumnCount is the number of columns of a row.

func (*Stmt) ColumnDeclType

func (s *Stmt) ColumnDeclType(i int) string

ColumnDeclType is the declared type of column i, or "".

func (*Stmt) ColumnDouble

func (s *Stmt) ColumnDouble(i int) float64

func (*Stmt) ColumnInt64

func (s *Stmt) ColumnInt64(i int) int64

func (*Stmt) ColumnName

func (s *Stmt) ColumnName(i int) string

func (*Stmt) ColumnText

func (s *Stmt) ColumnText(i int) (string, error)

ColumnText is the text of column i, copied. It fails when SQLite has no memory for it: it allocates to give as UTF-8 a text it holds as UTF-16 (a database in UTF-16) or a value that is no text.

func (*Stmt) ColumnType

func (s *Stmt) ColumnType(i int) int

func (*Stmt) Finalize

func (s *Stmt) Finalize() error

Finalize frees the statement.

func (*Stmt) IsExplain added in v0.1.5

func (s *Stmt) IsExplain() bool

IsExplain says the statement is an EXPLAIN or EXPLAIN QUERY PLAN.

func (*Stmt) Mergeable

func (s *Stmt) Mergeable() bool

Mergeable says the statement changes tables of the main database and touches nothing only its connection has: run on another connection of the same file, it does the same. After SQLite prepared the statement again (a change of the schema can add a trigger or make a table a virtual one), it is sorted again first.

func (*Stmt) ParamCount

func (s *Stmt) ParamCount() int

ParamCount is the number of the largest parameter.

func (*Stmt) ParamName

func (s *Stmt) ParamName(i int) string

ParamName is the name of parameter i (from 1), with its prefix, or "".

func (*Stmt) Private added in v0.1.5

func (s *Stmt) Private() bool

Private says the statement, as prepared, is not plain DML or a query of the main database: a PRAGMA, ATTACH, a read of another schema, a function that reads the connection's state (goClassify's GO_PRIVATE).

func (*Stmt) ReadOnly

func (s *Stmt) ReadOnly() bool

ReadOnly says whether the statement writes nothing: SQLite counts it as read-only, or it is an EXPLAIN.

func (*Stmt) Reclassify added in v0.1.3

func (s *Stmt) Reclassify()

Reclassify makes the next Mergeable sort the statement again: SQLite failed to prepare it again while the connection merged (SetMerging).

func (*Stmt) Reprepares

func (s *Stmt) Reprepares() int

Reprepares is how many times SQLite prepared the statement again, after a change of the schema.

func (*Stmt) Reset

func (s *Stmt) Reset() error

Reset makes the statement ready to run again. Bindings stay.

func (*Stmt) Step

func (s *Stmt) Step() (bool, error)

Step runs the statement to its next row: true when there is one.

type VCursor added in v0.1.3

type VCursor interface {
	// Filter starts the scan, with the plan of BestIndex: idxNum and idxStr
	// as it set them, and the values of the constraints it gave an
	// ArgvIndex, in that order.
	Filter(idxNum int, idxStr string, args []driver.Value) error
	Next() error
	// EOF says the scan is past its last row.
	EOF() bool
	// Column is column i of the row, as a Func result.
	Column(i int) (driver.Value, error)
	RowID() (int64, error)
	Close() error
}

VCursor is a scan of a VTable.

type VSavepointer added in v0.1.3

type VSavepointer interface {
	Savepoint(n int) error
	Release(n int) error
	RollbackTo(n int) error
}

VSavepointer is a VTransactor that keeps savepoints, so that a statement that fails inside a transaction is undone: Savepoint(n) marks the state, RollbackTo(n) goes back to the state at savepoint n (at Begin when the table joined after n), Release(n) forgets the marks from n on.

type VTable added in v0.1.3

type VTable interface {
	// Schema is the CREATE TABLE statement of its columns. Its name is not
	// used. A column marked HIDDEN is an argument of the module's name used
	// as a function.
	Schema() string
	// BestIndex says how a scan with the constraints of info would go. It
	// returns ErrConstraint when the scan cannot go with the constraints
	// that are usable.
	BestIndex(info *IndexInfo) error
	// Open makes a cursor for a scan.
	Open() (VCursor, error)
	// Disconnect ends the table on its connection.
	Disconnect() error
}

VTable is a table of a module on one connection. It only reads.

type VTransactor added in v0.1.3

type VTransactor interface {
	Begin() error
	Sync() error
	Commit() error
	Rollback() error
}

VTransactor is a VUpdater that takes part in the transactions of its connection: Begin before the first write of a transaction and as the table is made (goWritableCreate), Sync and Commit at its commit, Rollback at its rollback.

type VUpdater added in v0.1.3

type VUpdater interface {
	// Insert adds a row of the values cols. rowid is nil when the statement
	// gave none, and Insert chooses it. It returns the rowid of the row.
	Insert(rowid driver.Value, cols []driver.Value) (int64, error)
	// Update changes the row oldRowid to newRowid and cols.
	Update(oldRowid, newRowid driver.Value, cols []driver.Value) error
	Delete(rowid driver.Value) error
}

VUpdater is a VTable that takes writes, made by a module with ModWritable. A rowid is an int64, or the PRIMARY KEY of a WITHOUT ROWID table.

type WALHeader added in v0.1.3

type WALHeader struct {
	Change    uint32 // counts the transactions written
	BigEndian bool   // the frame checksums are computed on big-endian words
	PageSize  int
	MaxFrame  uint32    // the last frame of the last transaction the read transaction sees
	Pages     uint32    // the size of the database in pages
	Checksum  [2]uint32 // the checksum of frame MaxFrame
	Salt      [8]byte   // the salts of the WAL, as its header and its frames hold them
}

WALHeader is the header of the WAL a read transaction reads: struct WalIndexHdr of SQLite's wal.c, also the header of the -shm file.

type WindowAgg added in v0.1.3

type WindowAgg interface {
	Agg
	Value() (driver.Value, error)
	Inverse(args []driver.Value) error
}

WindowAgg is an Agg that is also an aggregate window function: Value gives the result for the rows of the frame so far, and Inverse takes out a row that left the frame, with the arguments Step had for it.

Jump to

Keyboard shortcuts

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