sqlite

package module
v1.19.2 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2022 License: BSD-3-Clause Imports: 18 Imported by: 1,720

README

sqlite

Package sqlite is a cgo-free port of SQLite. Although you could see mattn's driver (github.com/mattn/go-sqlite3) in go.mod file, we import it for tests only.

SQLite is an in-process implementation of a self-contained, serverless, zero-configuration, transactional SQL database engine.

Thanks

This project is sponsored by Schleibinger Geräte Teubert u. Greim GmbH by allowing one of the maintainers to work on it also in office hours.

Installation

$ go get modernc.org/sqlite

Documentation

godoc.org/modernc.org/sqlite

Builders

modern-c.appspot.com/-/builder/?importpath=modernc.org%2fsqlite

Documentation

Overview

Package sqlite is a sql/database driver using a CGo-free port of the C SQLite3 library.

SQLite is an in-process implementation of a self-contained, serverless, zero-configuration, transactional SQL database engine.

Thanks

This project is sponsored by Schleibinger Geräte Teubert u. Greim GmbH by allowing one of the maintainers to work on it also in office hours.

Supported platforms and architectures

These combinations of GOOS and GOARCH are currently supported 

OS      Arch    SQLite version
------------------------------
darwin	amd64   3.39.3
darwin	arm64   3.39.3
freebsd	amd64   3.39.3
freebsd	arm64   3.39.3
linux	386     3.39.3
linux	amd64   3.39.3
linux	arm     3.39.3
linux	arm64   3.39.3
linux	riscv64 3.39.3
windows	amd64   3.39.3
windows	arm64   3.39.3

Builders

Builder results available at 

https://modern-c.appspot.com/-/builder/?importpath=modernc.org%2fsqlite

Changelog

2022-09-16 v1.19.0:

Support frebsd/arm64.

2022-07-26 v1.18.0:

Adds support for Go fs.FS based SQLite virtual filesystems, see function New in modernc.org/sqlite/vfs and/or TestVFS in all_test.go

2022-04-24 v1.17.0:

Support windows/arm64.

2022-04-04 v1.16.0:

Support scalar application defined functions written in Go. 

https://www.sqlite.org/appfunc.html

2022-03-13 v1.15.0:

Support linux/riscv64.

2021-11-13 v1.14.0:

Support windows/amd64. This target had previously only experimental status because of a now resolved memory leak.

2021-09-07 v1.13.0:

Support freebsd/amd64.

Changelog

2021-06-23 v1.11.0:

Upgrade to use sqlite 3.36.0, release notes at https://www.sqlite.org/releaselog/3_36_0.html.

2021-05-06 v1.10.6:

Fixes a memory corruption issue (https://gitlab.com/cznic/sqlite/-/issues/53). Versions since v1.8.6 were affected and should be updated to v1.10.6.

2021-03-14 v1.10.0:

Update to use sqlite 3.35.0, release notes at https://www.sqlite.org/releaselog/3_35_0.html.

2021-03-11 v1.9.0:

Support darwin/arm64.

2021-01-08 v1.8.0:

Support darwin/amd64.

2020-09-13 v1.7.0:

Support linux/arm and linux/arm64.

2020-09-08 v1.6.0:

Support linux/386.

2020-09-03 v1.5.0:

This project is now completely CGo-free, including the Tcl tests.

2020-08-26 v1.4.0:

First stable release for linux/amd64. The database/sql driver and its tests are CGo free. Tests of the translated sqlite3.c library still require CGo. 

$ make full

...

SQLite 2020-08-14 13:23:32 fca8dc8b578f215a969cd899336378966156154710873e68b3d9ac5881b0ff3f
0 errors out of 928271 tests on 3900x Linux 64-bit little-endian
WARNING: Multi-threaded tests skipped: Linked against a non-threadsafe Tcl build
All memory allocations freed - no leaks
Maximum memory usage: 9156360 bytes
Current memory usage: 0 bytes
Number of malloc()  : -1 calls
--- PASS: TestTclTest (1785.04s)
PASS
ok  	modernc.org/sqlite	1785.041s
$

2020-07-26 v1.4.0-beta1:

The project has reached beta status while supporting linux/amd64 only at the moment. The 'extraquick' Tcl testsuite reports 

630 errors out of 200177 tests on  Linux 64-bit little-endian

and some memory leaks 

Unfreed memory: 698816 bytes in 322 allocations

2019-12-28 v1.2.0-alpha.3: Third alpha fixes issue #19.

It also bumps the minor version as the repository was wrongly already tagged with v1.1.0 before. Even though the tag was deleted there are proxies that cached that tag. Thanks /u/garaktailor for detecting the problem and suggesting this solution.

2019-12-26 v1.1.0-alpha.2: Second alpha release adds support for accessing a database concurrently by multiple goroutines and/or processes. v1.1.0 is now considered feature-complete. Next planed release should be a beta with a proper test suite.

2019-12-18 v1.1.0-alpha.1: First alpha release using the new cc/v3, gocc, qbe toolchain. Some primitive tests pass on linux_{amd64,386}. Not yet safe for concurrent access by multiple goroutines. Next alpha release is planed to arrive before the end of this year.

2017-06-10 Windows/Intel no more uses the VM (thanks Steffen Butzer).

2017-06-05 Linux/Intel no more uses the VM (cznic/virtual).

Connecting to a database

To access a Sqlite database do something like 

import (
	"database/sql"

	_ "modernc.org/sqlite"
)

...

db, err := sql.Open("sqlite", dsnURI)

...

Debug and development versions

A comma separated list of options can be passed to `go generate` via the environment variable GO_GENERATE. Some useful options include for example: 

-DSQLITE_DEBUG
-DSQLITE_MEM_DEBUG
-ccgo-verify-structs

To create a debug/development version, issue for example: 

$ GO_GENERATE=-DSQLITE_DEBUG,-DSQLITE_MEM_DEBUG go generate

Note: To run `go generate` you need to have modernc.org/ccgo/v3 installed.

Sqlite documentation

See https://sqlite.org/docs.html

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrorCodeString maps Error.Code() to its string representation.
	ErrorCodeString = map[int]string{
		sqlite3.SQLITE_ABORT:             "Callback routine requested an abort (SQLITE_ABORT)",
		sqlite3.SQLITE_AUTH:              "Authorization denied (SQLITE_AUTH)",
		sqlite3.SQLITE_BUSY:              "The database file is locked (SQLITE_BUSY)",
		sqlite3.SQLITE_CANTOPEN:          "Unable to open the database file (SQLITE_CANTOPEN)",
		sqlite3.SQLITE_CONSTRAINT:        "Abort due to constraint violation (SQLITE_CONSTRAINT)",
		sqlite3.SQLITE_CORRUPT:           "The database disk image is malformed (SQLITE_CORRUPT)",
		sqlite3.SQLITE_DONE:              "sqlite3_step() has finished executing (SQLITE_DONE)",
		sqlite3.SQLITE_EMPTY:             "Internal use only (SQLITE_EMPTY)",
		sqlite3.SQLITE_ERROR:             "Generic error (SQLITE_ERROR)",
		sqlite3.SQLITE_FORMAT:            "Not used (SQLITE_FORMAT)",
		sqlite3.SQLITE_FULL:              "Insertion failed because database is full (SQLITE_FULL)",
		sqlite3.SQLITE_INTERNAL:          "Internal logic error in SQLite (SQLITE_INTERNAL)",
		sqlite3.SQLITE_INTERRUPT:         "Operation terminated by sqlite3_interrupt()(SQLITE_INTERRUPT)",
		sqlite3.SQLITE_IOERR | (1 << 8):  "(SQLITE_IOERR_READ)",
		sqlite3.SQLITE_IOERR | (10 << 8): "(SQLITE_IOERR_DELETE)",
		sqlite3.SQLITE_IOERR | (11 << 8): "(SQLITE_IOERR_BLOCKED)",
		sqlite3.SQLITE_IOERR | (12 << 8): "(SQLITE_IOERR_NOMEM)",
		sqlite3.SQLITE_IOERR | (13 << 8): "(SQLITE_IOERR_ACCESS)",
		sqlite3.SQLITE_IOERR | (14 << 8): "(SQLITE_IOERR_CHECKRESERVEDLOCK)",
		sqlite3.SQLITE_IOERR | (15 << 8): "(SQLITE_IOERR_LOCK)",
		sqlite3.SQLITE_IOERR | (16 << 8): "(SQLITE_IOERR_CLOSE)",
		sqlite3.SQLITE_IOERR | (17 << 8): "(SQLITE_IOERR_DIR_CLOSE)",
		sqlite3.SQLITE_IOERR | (2 << 8):  "(SQLITE_IOERR_SHORT_READ)",
		sqlite3.SQLITE_IOERR | (3 << 8):  "(SQLITE_IOERR_WRITE)",
		sqlite3.SQLITE_IOERR | (4 << 8):  "(SQLITE_IOERR_FSYNC)",
		sqlite3.SQLITE_IOERR | (5 << 8):  "(SQLITE_IOERR_DIR_FSYNC)",
		sqlite3.SQLITE_IOERR | (6 << 8):  "(SQLITE_IOERR_TRUNCATE)",
		sqlite3.SQLITE_IOERR | (7 << 8):  "(SQLITE_IOERR_FSTAT)",
		sqlite3.SQLITE_IOERR | (8 << 8):  "(SQLITE_IOERR_UNLOCK)",
		sqlite3.SQLITE_IOERR | (9 << 8):  "(SQLITE_IOERR_RDLOCK)",
		sqlite3.SQLITE_IOERR:             "Some kind of disk I/O error occurred (SQLITE_IOERR)",
		sqlite3.SQLITE_LOCKED | (1 << 8): "(SQLITE_LOCKED_SHAREDCACHE)",
		sqlite3.SQLITE_LOCKED:            "A table in the database is locked (SQLITE_LOCKED)",
		sqlite3.SQLITE_MISMATCH:          "Data type mismatch (SQLITE_MISMATCH)",
		sqlite3.SQLITE_MISUSE:            "Library used incorrectly (SQLITE_MISUSE)",
		sqlite3.SQLITE_NOLFS:             "Uses OS features not supported on host (SQLITE_NOLFS)",
		sqlite3.SQLITE_NOMEM:             "A malloc() failed (SQLITE_NOMEM)",
		sqlite3.SQLITE_NOTADB:            "File opened that is not a database file (SQLITE_NOTADB)",
		sqlite3.SQLITE_NOTFOUND:          "Unknown opcode in sqlite3_file_control() (SQLITE_NOTFOUND)",
		sqlite3.SQLITE_NOTICE:            "Notifications from sqlite3_log() (SQLITE_NOTICE)",
		sqlite3.SQLITE_PERM:              "Access permission denied (SQLITE_PERM)",
		sqlite3.SQLITE_PROTOCOL:          "Database lock protocol error (SQLITE_PROTOCOL)",
		sqlite3.SQLITE_RANGE:             "2nd parameter to sqlite3_bind out of range (SQLITE_RANGE)",
		sqlite3.SQLITE_READONLY:          "Attempt to write a readonly database (SQLITE_READONLY)",
		sqlite3.SQLITE_ROW:               "sqlite3_step() has another row ready (SQLITE_ROW)",
		sqlite3.SQLITE_SCHEMA:            "The database schema changed (SQLITE_SCHEMA)",
		sqlite3.SQLITE_TOOBIG:            "String or BLOB exceeds size limit (SQLITE_TOOBIG)",
		sqlite3.SQLITE_WARNING:           "Warnings from sqlite3_log() (SQLITE_WARNING)",
	}
)

Functions

func MustRegisterDeterministicScalarFunction added in v1.16.0 

func MustRegisterDeterministicScalarFunction(
	zFuncName string,
	nArg int32,
	xFunc func(ctx *FunctionContext, args []driver.Value) (driver.Value, error),
)

MustRegisterDeterministicScalarFunction is like RegisterDeterministicScalarFunction but panics on error.

func MustRegisterScalarFunction added in v1.16.0 

func MustRegisterScalarFunction(
	zFuncName string,
	nArg int32,
	xFunc func(ctx *FunctionContext, args []driver.Value) (driver.Value, error),
)

MustRegisterScalarFunction is like RegisterScalarFunction but panics on error.

func RegisterDeterministicScalarFunction added in v1.16.0 

func RegisterDeterministicScalarFunction(
	zFuncName string,
	nArg int32,
	xFunc func(ctx *FunctionContext, args []driver.Value) (driver.Value, error),
) error

RegisterDeterministicScalarFunction registers a deterministic scalar function named zFuncName with nArg arguments. Passing -1 for nArg indicates the function is variadic. A deterministic function means that the function always gives the same output when the input parameters are the same.

The new function will be available to all new connections opened after executing RegisterDeterministicScalarFunction.

func RegisterScalarFunction added in v1.16.0 

func RegisterScalarFunction(
	zFuncName string,
	nArg int32,
	xFunc func(ctx *FunctionContext, args []driver.Value) (driver.Value, error),
) error

RegisterScalarFunction registers a scalar function named zFuncName with nArg arguments. Passing -1 for nArg indicates the function is variadic.

The new function will be available to all new connections opened after executing RegisterScalarFunction.

Types

type Driver 

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

Driver implements database/sql/driver.Driver.

func (*Driver) Open 

func (d *Driver) Open(name string) (driver.Conn, error)

Open returns a new connection to the database. The name is a string in a driver-specific format.

Open may return a cached connection (one previously closed), but doing so is unnecessary; the sql package maintains a pool of idle connections for efficient re-use.

The returned connection is only used by one goroutine at a time.

If name contains a '?', what follows is treated as a query string. This driver supports the following query parameters:

_pragma: Each value will be run as a "PRAGMA ..." statement (with the PRAGMA keyword added for you). May be specified more than once. Example: "_pragma=foreign_keys(1)" will enable foreign key enforcement. More information on supported PRAGMAs is available from the SQLite documentation: https://www.sqlite.org/pragma.html

_time_format: The name of a format to use when writing time values to the database. Currently the only supported value is "sqlite", which corresponds to format 7 from https://www.sqlite.org/lang_datefunc.html#time_values, including the timezone specifier. If this parameter is not specified, then the default String() format will be used.

_txlock: The locking behavior to use when beginning a transaction. May be "deferred", "immediate", or "exclusive" (case insensitive). The default is to not specify one, which SQLite maps to "deferred". More information is available at https://www.sqlite.org/lang_transaction.html#deferred_immediate_and_exclusive_transactions

type Error added in v1.3.0 

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

Error represents sqlite library error code.

func (*Error) Code added in v1.3.0 

func (e *Error) Code() int

Code returns the sqlite result code for this error.

func (*Error) Error added in v1.3.0 

func (e *Error) Error() string

Error implements error.

type FunctionContext added in v1.16.0 

type FunctionContext struct{}

FunctionContext represents the context user defined functions execute in. Fields and/or methods of this type may get addedd in the future.

Source Files

View all Source files

Directories

Path Synopsis
benchmark module
examples
example1
internal
libc2
mptest
testfixture
driver
driver/drivers

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.