sqliter

package module
v0.4.166 Latest Latest
Warning

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

 Go to latest Published: May 3, 2024 License: ISC Imports: 17 Imported by: 0

Documentation

Overview

Package sqliter provides partitioning, cached prepared statements and data conversion for SQLite3.

conversions for:

additionally:

Index

Constants

View Source 
const (
	// SQLite3 special filename for in-memory databases
	SQLiteMemoryDataSourceName = ":memory:"
	// name of the SQLite3 database driver
	//	- “modernc.org/sqlite”
	SQLiteDriverName = "sqlite"
)
View Source 
const (
	CodeBusy                    = 5    // sqlite3.SQLITE_BUSY
	CodeConstraintFailedNOTNULL = 1299 // SQLITE_CONSTRAINT_NOTNULL
	CodeConstraintFailedUNIQUE  = 2067 // SQLITE_CONSTRAINT_UNIQUE
	CodeDatabaseIsLocked        = 261  // locked WAL file
)

SQLite errors are of type sqlite.Error

  • sqlite.Error has a code int value
  • Some code values are not exported
  • For calling code to not have to import the driver itself, frequent error-code values are here

Variables

View Source 
var DSNrFactory = &dSNrFactory{}

DSNrFactory provides an abstract factory method for an SQLite3 data-source namer

View Source 
var ErrDsnNotExist = &dsnNotExist{error: errors.New("ErrDsnNotExist")}

ErrDsnNotExist can detect DSN not exist errors

Usage: 

if errors.Is(err, sqliter.ErrDsnNotExist) {

Functions

func BoolToDB added in v0.4.14 

func BoolToDB(b bool) (dbValue int)

BoolToDB converts Go bool to SQLite INTEGER

  • Go reflect type is bool
  • SQLite storage class for Boolean Datatype is INTEGER
  • SQLite values used are 0 or 1

func DATETIMEtoTime added in v0.4.127 

func DATETIMEtoTime(sqliteText string) (t time.Time, err error)

DATETIMEtoTime converts SQLite DATETIME to Go time.Time with location time.Local

  • better to use is TimeToDB and ToTime using iso8601 utc time-zone with nanosecond precision
  • database stores as TEXT in UTC, millisecond precision
  • “2019-01-01 21:30:42.000 +00:00”

func MarkDsnNotExist added in v0.4.127 

func MarkDsnNotExist(err error) (err2 error)

MarkDsnNotExist marks error as cased by read-only DSN

func NullableToTime added in v0.4.18 

func NullableToTime(nullString sql.NullString) (t time.Time, err error)

NullableToTime parses SQLite TEXT to Go time.Time in Local location

  • nullable database column
  • SQLite TEXT ISO8601 nano-second resolution UTC time zone
  • SQLite TEXT: “2022-01-01T08:00:00.000000000Z”
  • NULL corresponds to time.Time{} time.Time.IsZero true

func OpenDataSource added in v0.4.127 

func OpenDataSource(dataSourceName parl.DataSourceName) (dataSource parl.DataSource, err error)

OpenDataSource creates a database-file in the file-system and returns its database implementation

func OpenDataSourceNamer added in v0.4.127 

func OpenDataSourceNamer(appName string) (dsnr parl.DataSourceNamer, err error)

OpenDataSourceNamer is a parl.DSNrFactory function that returns a SQLite3 data-source names that returns:

  • SQLite3 database filenames based on a partition key
  • SQLite3 implemented data sources providing generic SQL query execution

func OpenDataSourceNamerRO added in v0.4.127 

func OpenDataSourceNamerRO(appName string) (dsn parl.DataSourceNamer, err error)

OpenDataSourceNamerRO returns a SQLIte3 parl.DataSourceNamer that does not create databases or write to the file-system

  • errors can be checked to be cause by read-only:

Usage: 

if errors.Is(err, sqliter.ErrDsnNotExist) {

func Pragma added in v0.4.127 

func Pragma(dataSource parl.DataSource, ctx context.Context) (pragmas map[string]string, err error)

Pragma returns some common SQLite3 database settings

  • parl.DataSource is a caching of prepared statements obatined from OpenDataSource

func PragmaDB added in v0.4.127 

func PragmaDB(db parl.DB, partition parl.DBPartition, ctx context.Context) (pragmas map[string]string, err error)

Pragma returns some common SQLite3 database settings

  • parl.DB is a map of multiple DB objects facilitating partitioning
  • in normal use parl.DB is not available from psql.NewDBMap

func PragmaSQL added in v0.4.136 

func PragmaSQL(sqlDB *sql.DB, ctx context.Context) (pragmas map[string]string, err error)

Pragma returns some common SQLite3 database settings

  • sqlDB is obtained from sql.Open
  • in-memory returns: map[foreignKeys:0 journal:memory timeout:0]

func TimeToDATETIME added in v0.4.127 

func TimeToDATETIME(t time.Time) (dateTime string)

TimeToDATETIME converts Go time.Time to SQLite DATETIME UTC millisecond precision

  • better to use is TimeToDB and ToTime using iso8601 utc time-zone with nanosecond precision
  • “2019-01-01 21:30:42.000 +00:00”

func TimeToDB added in v0.4.14 

func TimeToDB(t time.Time) (dbValue string)

TimeToDB converts ns-resolution Go time.Time in any time.Location to SQLite TEXT ISO8601 nano-second resolution UTC time zone

  • SQLite TEXT: “2022-01-01T08:00:00.000000000Z”

func TimeToDBNullable added in v0.4.18 

func TimeToDBNullable(t time.Time) (dbValue any)

TimeToDBNullable converts ns-resolution Go time.Time in any time.Location to SQLite TEXT ISO8601 nano-second resolution UTC time zone

  • for nullable database column
  • SQLite TEXT: “2022-01-01T08:00:00.000000000Z”
  • NULL corresponds to time.Time{} time.Time.IsZero true

func ToBool added in v0.4.14 

func ToBool(dbValue int) (b bool, err error)

ToBool converts SQLite INTEGER 0 or 1 to Go bool

  • Go reflect type is bool
  • SQLite INTEGER values are 0 or 1

func ToTime added in v0.4.14 

func ToTime(timeString string) (t time.Time, err error)

ToTime parses SQLite TEXT to Go time.Time in Local location

  • SQLite TEXT ISO8601 nano-second resolution UTC time zone
  • SQLite TEXT: “2022-01-01T08:00:00.000000000Z”

func ToUUID added in v0.4.14 

func ToUUID(IDString string) (ID uuid.UUID, err error)

ToUUID converts an SQLite TEXT value to Go uuid.UUID

  • err: non-nil on failure
  • ID: valid or zero-value on failure
  • Go reflect type: [16]byte uuid.UUID from package github.com/google/uuid
  • — 16×8 is 128 bits
  • SQLite value: 36-character TEXT “01234567-89ab-cdef-0123-456789abcdef”
  • — 32×4 is 128 bits

func UUIDToDB added in v0.4.14 

func UUIDToDB(ID uuid.UUID) (dbValue string)

UUIDToDB stores a Go 128-bit UUID as 36 characters SQLite TEXT

  • Go reflect type: array [16]byte from package github.com/google/uuid
  • — 16×8 is 128 bits
  • SQLite type: 36-character string TEXT “01234567-89ab-cdef-0123-456789abcdef”
  • — 32×4 is 128 bits
  • — SQLite Storage Classes: NULL INTEGER REAL TEXT BLOB

Types

type DataSource added in v0.4.12 

type DataSource struct {
	// DB represents a generic SQL database that can:
	//	- offer connections
	//	- execute generuic SQL queries
	*sql.DB
	// contains filtered or unexported fields
}

DataSource represents a SQL database that can prepare generic SQL queries

func (*DataSource) WrapStmt added in v0.4.26 

func (ds *DataSource) WrapStmt(stmt *sql.Stmt) (stm psql2.Stmt)

PrepareContext returns a sql.Stmt that does retries on 5 SQLITE_BUSY

  • this is used by [parl.psql]

type DataSourceNamer added in v0.4.12 

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

DataSourceNamer provides partitioned SQLite3 database files within the user’s home directory

func (*DataSourceNamer) DSN added in v0.4.12 

func (n *DataSourceNamer) DSN(year ...parl.DBPartition) (dsnr parl.DataSourceName)

DSN returns a data source name, ie. a filename from application name and a partition key like year

  • effectyively an absolute path of a writable SQLite3 “.db” database file
  • implements parl’s [DatasourceNamer.DSN]

func (*DataSourceNamer) DataSource added in v0.4.12 

func (n *DataSourceNamer) DataSource(dataSourceName parl.DataSourceName) (dataSource parl.DataSource, err error)

DataSource returns a data-source that can execute generic SQL queries based on a data-source name

  • implements parl’s [DatasourceNamer.DataSource]

type DataSourceNamerRO added in v0.4.127 

type DataSourceNamerRO struct {
	DataSourceNamer
}

DataSourceNamerRO is a SQLite3 data source that does not create files or directories

func (*DataSourceNamerRO) DataSource added in v0.4.127 

func (n *DataSourceNamerRO) DataSource(dataSourceName parl.DataSourceName) (dataSource parl.DataSource, err error)

DataSource does not create database files

  • dataSourceName is the path toa file-syste database file
  • make sure it already exists

type ErrorCode added in v0.4.13 

type ErrorCode interface {
	error
	Code() (code int)
}

ErrorCode is the SQLite error implementation

  • ErrorCode is an error instance
  • The Code method provides an int error code

func Code added in v0.4.14 

func Code(err error) (code int, sqliteError ErrorCode)

GetErrorCode traverses an error chain looking for an SQLite error

  • If an SQLite error is found, it is returned in sqliteError
  • — code is the int error code
  • If no SQLite error exists in the error chain, sqliteError is nil and code is 0

type Stmt added in v0.4.26 

type Stmt struct {
	*sql.Stmt
	// contains filtered or unexported fields
}

Stmt implements retries for a SQLite3 table

  • the code here implements retries due to SQLite3 producing various concurrency errors
  • this is legacy code from 2022-06

func (*Stmt) ExecContext added in v0.4.26 

func (st *Stmt) ExecContext(ctx context.Context, args ...any) (sqlResult sql.Result, err error)

ExecContext executes a SQL statements that does not return any rows

  • for performance reasons cached prepared statements are used
  • the code here implements retries due to SQLite3 producing various concurrency errors
  • this is legacy code from 2022-06

func (*Stmt) QueryContext added in v0.4.26 

func (st *Stmt) QueryContext(ctx context.Context, args ...any) (sqlRows *sql.Rows, err error)

QueryContext executes a SQL statements that may return multiple rows

  • for performance reasons cached prepared statements are used
  • the code here implements retries due to SQLite3 producing various concurrency errors
  • this is legacy code from 2022-06

func (*Stmt) QueryRowContext added in v0.4.26 

func (st *Stmt) QueryRowContext(ctx context.Context, args ...any) (sqlRow *sql.Row)

QueryRowContext executes a SQL statements that returns exactly one row

  • for performance reasons cached prepared statements are used
  • the code here implements retries due to SQLite3 producing various concurrency errors
  • this is legacy code from 2022-06

Source Files

View all Source files

Jump to

Keyboard shortcuts

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