sqlite3vfs

README

sqlite3vfs: Go sqlite3 VFS API

sqlite3vfs is a Cgo API that allows you to create custom sqlite Virtual File Systems (VFS) in Go. You can use this with the sqlite3 https://github.com/mattn/go-sqlite3 SQL driver.

Basic usage

To use, simply implement the VFS and File interfaces. Then register your VFS with sqlite3vfs and include the vfs name when opening the database connection:

	// create your VFS
	vfs := newTempVFS()

	vfsName := "tmpfs"
	err := sqlite3vfs.RegisterVFS(vfsName, vfs)
	if err != nil {
		panic(err)
	}

	db, err := sql.Open("sqlite3", fmt.Sprintf("foo.db?vfs=%s", vfsName))
	if err != nil {
		panic(err)
	}

A full example can be found in sqlite3vfs_test.go.

Loadable SQLite3 module

sqlite3vfs can also be built as a SQLite3 loadable module. This allows you to load your vfs at runtime into applications that support SQLite3 modules, including the SQLite3 cli tool.

To build as a loadable module, set the -tags SQLITE3VFS_LOADABLE_EXT build tag. Both DonutDB and sqlite3vfshttp have working examples of building a SQLite3 loadable module.

Users

• DonutDB: SQLite on top of DynamoDB (read/write)
• sqlite3vfshttp: Query a SQLite database over HTTP using range requests
• sqlitezstd: Query a SQLite database that had been compressed with zstd seekable

Documentation

Index

• Variables
• func RegisterVFS(name string, vfs VFS, opts ...Option) error
• type AccessFlag
• type DeviceCharacteristic
• type ExtendedVFSv1
• type File
• type LockType
  • func (lt LockType) String() string
• type OpenFlag
• type Option
  • func WithMaxPathName(n int) Option
• type SyncType
• type VFS

Variables

var (
	GenericError    = sqliteError{1, "Generic Error"}
	InternalError   = sqliteError{2, "Internal Error"}
	PermError       = sqliteError{3, "Perm Error"}
	AbortError      = sqliteError{4, "Abort Error"}
	BusyError       = sqliteError{5, "Busy Error"}
	LockedError     = sqliteError{6, "Locked Error"}
	NoMemError      = sqliteError{7, "No Mem Error"}
	ReadOnlyError   = sqliteError{8, "Read Only Error"}
	InterruptError  = sqliteError{9, "Interrupt Error"}
	IOError         = sqliteError{10, "IO Error"}
	CorruptError    = sqliteError{11, "Corrupt Error"}
	NotFoundError   = sqliteError{12, "Not Found Error"}
	FullError       = sqliteError{13, "Full Error"}
	CantOpenError   = sqliteError{14, "CantOpen Error"}
	ProtocolError   = sqliteError{15, "Protocol Error"}
	EmptyError      = sqliteError{16, "Empty Error"}
	SchemaError     = sqliteError{17, "Schema Error"}
	TooBigError     = sqliteError{18, "TooBig Error"}
	ConstraintError = sqliteError{19, "Constraint Error"}
	MismatchError   = sqliteError{20, "Mismatch Error"}
	MisuseError     = sqliteError{21, "Misuse Error"}
	NoLFSError      = sqliteError{22, "No Large File Support Error"}
	AuthError       = sqliteError{23, "Auth Error"}
	FormatError     = sqliteError{24, "Format Error"}
	RangeError      = sqliteError{25, "Range Error"}
	NotaDBError     = sqliteError{26, "Not a DB Error"}
	NoticeError     = sqliteError{27, "Notice Error"}
	WarningError    = sqliteError{28, "Warning Error"}

	IOErrorRead      = sqliteError{266, "IO Error Read"}
	IOErrorShortRead = sqliteError{522, "IO Error Short Read"}
	IOErrorWrite     = sqliteError{778, "IO Error Write"}
)

Functions

func RegisterVFS

func RegisterVFS(name string, vfs VFS, opts ...Option) error

Register a VFS with sqlite. The name specified must be unique and should match the name given when opening the database: `?vfs={{name}}`.

Types

type AccessFlag

type AccessFlag int

const (
	AccessExists    AccessFlag = 0 // Does the file exist?
	AccessReadWrite AccessFlag = 1 // Is the file both readable and writeable?
	AccessRead      AccessFlag = 2 // Is the file readable?

)

type DeviceCharacteristic

type DeviceCharacteristic int

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

const (
	IocapAtomic              DeviceCharacteristic = 0x00000001
	IocapAtomic512           DeviceCharacteristic = 0x00000002
	IocapAtomic1K            DeviceCharacteristic = 0x00000004
	IocapAtomic2K            DeviceCharacteristic = 0x00000008
	IocapAtomic4K            DeviceCharacteristic = 0x00000010
	IocapAtomic8K            DeviceCharacteristic = 0x00000020
	IocapAtomic16K           DeviceCharacteristic = 0x00000040
	IocapAtomic32K           DeviceCharacteristic = 0x00000080
	IocapAtomic64K           DeviceCharacteristic = 0x00000100
	IocapSafeAppend          DeviceCharacteristic = 0x00000200
	IocapSequential          DeviceCharacteristic = 0x00000400
	IocapUndeletableWhenOpen DeviceCharacteristic = 0x00000800
	IocapPowersafeOverwrite  DeviceCharacteristic = 0x00001000
	IocapImmutable           DeviceCharacteristic = 0x00002000
	IocapBatchAtomic         DeviceCharacteristic = 0x00004000
)

type ExtendedVFSv1

type ExtendedVFSv1 interface {
	VFS

	// Randomness populates n with pseudo-random data.
	// Returns the number of bytes of randomness obtained.
	Randomness(n []byte) int

	// Sleep for duration
	Sleep(d time.Duration)

	CurrentTime() time.Time
}

type File

type File interface {
	Close() error

	// ReadAt reads len(p) bytes into p starting at offset off in the underlying input source.
	// It returns the number of bytes read (0 <= n <= len(p)) and any error encountered.
	// If n < len(p), SQLITE_IOERR_SHORT_READ will be returned to sqlite.
	ReadAt(p []byte, off int64) (n int, err error)

	// WriteAt writes len(p) bytes from p to the underlying data stream at offset off.
	// It returns the number of bytes written from p (0 <= n <= len(p)) and any error encountered that caused the write to stop early.
	// WriteAt must return a non-nil error if it returns n < len(p).
	WriteAt(p []byte, off int64) (n int, err error)

	Truncate(size int64) error

	Sync(flag SyncType) error

	FileSize() (int64, error)

	// Acquire or upgrade a lock.
	// elock can be one of the following:
	// LockShared, LockReserved, LockPending, LockExclusive.
	//
	// Additional states can be inserted between the current lock level
	// and the requested lock level. The locking might fail on one of the later
	// transitions leaving the lock state different from what it started but
	// still short of its goal.  The following chart shows the allowed
	// transitions and the inserted intermediate states:
	//
	//    UNLOCKED -> SHARED
	//    SHARED -> RESERVED
	//    SHARED -> (PENDING) -> EXCLUSIVE
	//    RESERVED -> (PENDING) -> EXCLUSIVE
	//    PENDING -> EXCLUSIVE
	//
	// This function should only increase a lock level.
	// See the sqlite source documentation for unixLock for more details.
	Lock(elock LockType) error

	// Lower the locking level on file to eFileLock. eFileLock must be
	// either NO_LOCK or SHARED_LOCK. If the locking level of the file
	// descriptor is already at or below the requested locking level,
	// this routine is a no-op.
	Unlock(elock LockType) error

	// Check whether any database connection, either in this process or
	// in some other process, is holding a RESERVED, PENDING, or
	// EXCLUSIVE lock on the file. It returns true if such a lock exists
	// and false otherwise.
	CheckReservedLock() (bool, error)

	// SectorSize returns the sector size of the device that underlies
	// the file. The sector size is the minimum write that can be
	// performed without disturbing other bytes in the file.
	SectorSize() int64

	// DeviceCharacteristics returns a bit vector describing behaviors
	// of the underlying device.
	DeviceCharacteristics() DeviceCharacteristic
}

type LockType

type LockType int

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

const (
	LockNone      LockType = 0
	LockShared    LockType = 1
	LockReserved  LockType = 2
	LockPending   LockType = 3
	LockExclusive LockType = 4
)

func (LockType) String

func (lt LockType) String() string

type OpenFlag

type OpenFlag int

const (
	OpenReadOnly      OpenFlag = 0x00000001
	OpenReadWrite     OpenFlag = 0x00000002
	OpenCreate        OpenFlag = 0x00000004
	OpenDeleteOnClose OpenFlag = 0x00000008
	OpenExclusive     OpenFlag = 0x00000010
	OpenAutoProxy     OpenFlag = 0x00000020
	OpenURI           OpenFlag = 0x00000040
	OpenMemory        OpenFlag = 0x00000080
	OpenMainDB        OpenFlag = 0x00000100
	OpenTempDB        OpenFlag = 0x00000200
	OpenTransientDB   OpenFlag = 0x00000400
	OpenMainJournal   OpenFlag = 0x00000800
	OpenTempJournal   OpenFlag = 0x00001000
	OpenSubJournal    OpenFlag = 0x00002000
	OpenSuperJournal  OpenFlag = 0x00004000
	OpenNoMutex       OpenFlag = 0x00008000
	OpenFullMutex     OpenFlag = 0x00010000
	OpenSharedCache   OpenFlag = 0x00020000
	OpenPrivateCache  OpenFlag = 0x00040000
	OpenWAL           OpenFlag = 0x00080000
	OpenNoFollow      OpenFlag = 0x01000000
)

type Option

type Option interface {
	// contains filtered or unexported methods
}

func WithMaxPathName

func WithMaxPathName(n int) Option

type SyncType

type SyncType int

const (
	SyncNormal   SyncType = 0x00002
	SyncFull     SyncType = 0x00003
	SyncDataOnly SyncType = 0x00010
)

type VFS

type VFS interface {
	// Open a file.
	// Name will either be the name of the file to open or "" for a temp file.
	Open(name string, flags OpenFlag) (File, OpenFlag, error)

	// Delete the named file. If dirSync is true them ensure the file-system
	// modification has been synced to disk before returning.
	Delete(name string, dirSync bool) error

	// Test for access permission. Returns true if the requested permission is available.
	Access(name string, flags AccessFlag) (bool, error)

	// FullPathname returns the canonicalized version of name.
	FullPathname(name string) string
}