sqlite3vfs

https://pkg.go.dev/github.com/psanford/sqlite3vfs
Admin
sqlite3vfs is a Go Cgo library that enables developers to create custom SQLite Virtual File Systems...
Tokens:10,439
Snippets:58
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Register a custom VFS and open a database with sqlite3vfs

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Shows the basic usage: create a VFS, register it with sqlite3vfs.RegisterVFS, then open a database connection using the sqlite3 driver with the vfs query parameter. The example uses a placeholder newTempVFS() and panics on errors.

```go
	// 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)
	}


```

--------------------------------

### Build httpvfs.so and Query Remote Database with sqlite3 CLI

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfshttp

Shows building the httpvfs.so shared library from Go source and then using the sqlite3 CLI to load the extension, open a remote database, and run a query. Requires the SQLITE3VFSHTTP_URL environment variable set to the remote database URL.

```bash
$ cd sqlite3http-ext

# build httpvfs.so shared library
$ make
go build -tags SQLITE3VFS_LOADABLE_EXT -o sqlite3http_ext.a -buildmode=c-archive sqlite3http_ext.go
gcc -g -fPIC -shared -o httpvfs.so sqlite3http_ext.c sqlite3http_ext.a

# set url of sqlite3 db as environment variable SQLITE3VFSHTTP_URL:
$ export SQLITE3VFSHTTP_URL='https://www.sanford.io/demo.db'

$ sqlite3
SQLite version 3.31.1 2020-01-27 19:55:54
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
sqlite> -- load extention
sqlite> .load ./httpvfs
sqlite> -- open db using vfs=httpvfs, note you must use the sqlite uri syntax which starts with file://
sqlite> .open file:///foo.db?vfs=httpvfs
sqlite> -- query from remote db
sqlite> SELECT * from csv where period > '2010' limit 10;
series_reference period data_value suppressed status units magnitude subject group series_title_1
----------------- ---------- ---------- ---------- ---------- ---------- ---------- ------------------------- ---------------------------------------------------- -----------
BOPQ.S06AC000000000A 2010.03 17463 F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance         of Payments major components Actual
BOPQ.S06AC000000000A 2010.06 17463 F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of Payments major components Actual
BOPQ.S06AC000000000A 2010.09 17463 F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of Payments major components Actual
BOPQ.S06AC000000000A 2010.12 17463 F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of Payments major components Actual
BOPQ.S06AC000000000A 2010.03 17463 F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of Payments major components Actual
BOPQ.S06AC000000000A 2011.03 17463 F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of Payments major components Actual
BOPQ.S06AC000000000A 2011.06 17463 F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of Payments major components Actual
BOPQ.S06AC000000000A 2011.09 17463 F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of Payments major components Actual
BOPQ.S06AC000000000A 2011.12 17463 F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of Payments major components Actual
BOPQ.S06AC000000000A 2012.03 17463 F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of Payments major components Actual
BOPQ.S06AC000000000A 2012.06 17463 F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of Payments major components Actual

```

--------------------------------

### HttpVFS Open method

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfshttp

Opens a file within the VFS with the specified flags.

```go
func (vfs *HttpVFS) Open(name string, flags sqlite3vfs.OpenFlag) (sqlite3vfs.File, sqlite3vfs.OpenFlag, error)
```

--------------------------------

### URIOpener Interface

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

This section documents the URIOpener interface for opening files with URI parameters.

```APIDOC
## URIOpener.OpenURI

### Description
Opens a file with URI parameters. This is an optional interface that VFS implementations can implement to receive URI parameters supplied in the filename.

### Method
OpenURI

### Parameters
- **name** (string) - Required - The name of the file to open.
- **params** (map[string]string) - Required - URI parameters.
- **flags** (OpenFlag) - Required - Flags controlling the open behavior.

### Returns
- **File** - The opened file.
- **OpenFlag** - The actual flags used.
- **error** - Any error encountered.
```

--------------------------------

### Option interface and WithMaxPathName function

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Option interface with unexported methods, and a function to set the maximum path name length.

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

```go
func WithMaxPathName(n int) Option
```

--------------------------------

### VFS interface for file operations

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Defines the VFS interface for opening, deleting, and checking access to files. Open takes a name (or empty string for temp file) and flags, returning a File, OpenFlag, and error. Delete removes a file with optional directory sync. Access checks permissions.

```go
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)
}
```

--------------------------------

### VFS Interface

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

This section documents the VFS interface methods for opening, deleting, and checking access to files.

```APIDOC
## VFS.Open

### Description
Opens a file with the given name and flags. If name is empty, a temporary file is opened.

### Method
Open

### Parameters
- **name** (string) - Required - The name of the file to open, or "" for a temp file.
- **flags** (OpenFlag) - Required - Flags controlling the open behavior.

### Returns
- **File** - The opened file.
- **OpenFlag** - The actual flags used.
- **error** - Any error encountered.
```

```APIDOC
## VFS.Delete

### Description
Deletes the named file. If dirSync is true, ensures the file-system modification has been synced to disk before returning.

### Method
Delete

### Parameters
- **name** (string) - Required - The name of the file to delete.
- **dirSync** (bool) - Required - Whether to sync the directory to disk before returning.

### Returns
- **error** - Any error encountered.
```

```APIDOC
## VFS.Access

### Description
Tests for access permission on the named file. Returns true if the requested permission is available.

### Method
Access

### Parameters
- **name** (string) - Required - The name of the file to check.
- **flags** (AccessFlag) - Required - The permission flags to test.

### Returns
- **bool** - Whether the requested permission is available.
- **error** - Any error encountered.
```

```APIDOC
## File.Lock

### Description
Acquires or upgrades a lock on the file. The elock parameter can be one of LockShared, LockReserved, LockPending, or LockExclusive. The lock level can only increase.

### Method
Lock

### Parameters
- **elock** (LockType) - Required - The lock level to acquire or upgrade to.

### Returns
- **error** - Any error encountered.
```

```APIDOC
## File.Unlock

### Description
Lowers the locking level on the file to the specified level. The level must be either NO_LOCK or SHARED_LOCK. If the current level is already at or below the requested level, this is a no-op.

### Method
Unlock

### Parameters
- **elock** (LockType) - Required - The lock level to lower to.

### Returns
- **error** - Any error encountered.
```

```APIDOC
## File.CheckReservedLock

### Description
Checks whether any database connection (in this process or another) holds a RESERVED, PENDING, or EXCLUSIVE lock on the file. Returns true if such a lock exists.

### Method
CheckReservedLock

### Returns
- **bool** - Whether a reserved, pending, or exclusive lock exists.
- **error** - Any error encountered.
```

```APIDOC
## File.SectorSize

### Description
Returns the sector size of the underlying device. The sector size is the minimum write that can be performed without disturbing other bytes in the file.

### Method
SectorSize

### Returns
- **int64** - The sector size.
```

```APIDOC
## File.DeviceCharacteristics

### Description
Returns a bit vector describing behaviors of the underlying device.

### Method
DeviceCharacteristics

### Returns
- **DeviceCharacteristic** - The device characteristics bit vector.
```

```APIDOC
## FileController.FileControl

### Description
Handles file control operations. For SQLITE_FCNTL_PRAGMA operations, pragmaName contains the pragma name (e.g., "litestream_time") and pragmaValue contains the pragma value (nil for queries). Returns the result string (for queries) and any error.

### Method
FileControl

### Parameters
- **op** (int) - Required - The file control operation code.
- **pragmaName** (string) - Required - The pragma name (for SQLITE_FCNTL_PRAGMA).
- **pragmaValue** (*string) - Optional - The pragma value (nil for queries).

### Returns
- **string** - The result string (for queries).
- **error** - Any error encountered.
```

```APIDOC
## URIOpener.OpenURI

### Description
Opens a file with URI parameters. This is an optional interface that VFS implementations can implement to receive URI parameters supplied in the filename.

### Method
OpenURI

### Parameters
- **name** (string) - Required - The name of the file to open.
- **params** (map[string]string) - Required - URI parameters.
- **flags** (OpenFlag) - Required - Flags controlling the open behavior.

### Returns
- **File** - The opened file.
- **OpenFlag** - The actual flags used.
- **error** - Any error encountered.
```

--------------------------------

### FileController interface for file control operations

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Optional interface that File implementations can implement to handle file control operations like PRAGMA commands. For SQLITE_FCNTL_PRAGMA, pragmaName contains the pragma name (e.g., "litestream_time") and pragmaValue contains the value (nil for queries). Returns result string and error.

```go
type FileController interface {
	// FileControl handles file control operations.
	// For SQLITE_FCNTL_PRAGMA operations:
	//   - pragmaName contains the pragma name (e.g., "litestream_time")
	//   - pragmaValue contains the pragma value (nil for queries)
	// Returns the result string (for queries) and any error.
	// Return nil error with nil result for successful operations with no result.
	FileControl(op int, pragmaName string, pragmaValue *string) (*string, error)
}
```

--------------------------------

### HttpVFS FullPathname method

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfshttp

Returns the full pathname for a given file name.

```go
func (vfs *HttpVFS) FullPathname(name string) string
```

--------------------------------

### Query SQLite schema with sqlitehttpcli

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfshttp

Use the -url and -query flags to inspect the sqlite_master table of a remote database.

```bash
# query the sqlite schema table
$ ./sqlitehttpcli -url 'https://www.sanford.io/demo.db' -query 'select * from main.sqlite_master'
row: [table csv csv 2 CREATE TABLE csv (series_reference,
period,
data_value,
suppressed,
status,
units,
magntude,
subject,
grp,
series_title_1)]
```

--------------------------------

### AccessFlag Constants

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Constants for file access checks: AccessExists, AccessReadWrite, and AccessRead.

```go
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?

)
```

--------------------------------

### File Interface

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Defines the File interface for VFS file operations, including Close, ReadAt, WriteAt, Truncate, Sync, and FileSize. ReadAt and WriteAt have specific requirements for returning errors when short reads/writes occur.

```go
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)
}
```

--------------------------------

### File Interface

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

This section documents the File interface methods for locking, unlocking, checking locks, and retrieving device information.

```APIDOC
## File.Lock

### Description
Acquires or upgrades a lock on the file. The elock parameter can be one of LockShared, LockReserved, LockPending, or LockExclusive. The lock level can only increase.

### Method
Lock

### Parameters
- **elock** (LockType) - Required - The lock level to acquire or upgrade to.

### Returns
- **error** - Any error encountered.
```

```APIDOC
## File.Unlock

### Description
Lowers the locking level on the file to the specified level. The level must be either NO_LOCK or SHARED_LOCK. If the current level is already at or below the requested level, this is a no-op.

### Method
Unlock

### Parameters
- **elock** (LockType) - Required - The lock level to lower to.

### Returns
- **error** - Any error encountered.
```

```APIDOC
## File.CheckReservedLock

### Description
Checks whether any database connection (in this process or another) holds a RESERVED, PENDING, or EXCLUSIVE lock on the file. Returns true if such a lock exists.

### Method
CheckReservedLock

### Returns
- **bool** - Whether a reserved, pending, or exclusive lock exists.
- **error** - Any error encountered.
```

```APIDOC
## File.SectorSize

### Description
Returns the sector size of the underlying device. The sector size is the minimum write that can be performed without disturbing other bytes in the file.

### Method
SectorSize

### Returns
- **int64** - The sector size.
```

```APIDOC
## File.DeviceCharacteristics

### Description
Returns a bit vector describing behaviors of the underlying device.

### Method
DeviceCharacteristics

### Returns
- **DeviceCharacteristic** - The device characteristics bit vector.
```

--------------------------------

### URIOpener interface for URI parameters

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Optional interface that VFS implementations can implement to receive URI parameters supplied in the filename. OpenURI takes a name, params map, and flags, returning a File, OpenFlag, and error.

```go
type URIOpener interface {
	// OpenURI opens a file with URI parameters.
	OpenURI(name string, params map[string]string, flags OpenFlag) (File, OpenFlag, error)
}
```

--------------------------------

### RegisterVFS Function Signature

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Registers a VFS with sqlite. The name must be unique and should match the name given when opening the database using the ?vfs={{name}} parameter.

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

--------------------------------

### File interface with lock and file operations

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Defines the File interface for a VFS file, including lock management (Lock, Unlock, CheckReservedLock), sector size, and device characteristics. Lock transitions are documented: UNLOCKED -> SHARED, SHARED -> RESERVED, SHARED -> (PENDING) -> EXCLUSIVE, RESERVED -> (PENDING) -> EXCLUSIVE, PENDING -> EXCLUSIVE.

```go
// 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
}
```

--------------------------------

### Demo database schema for sqlite3vfshttp

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfshttp

Schema of the demo database hosted on a public webserver for testing. The table is named csv and contains ten columns with no explicit data types.

```sql
CREATE TABLE csv (series_reference,
period,
data_value,
suppressed,
status,
units,
magntude,
subject,
grp,
series_title_1);
```

--------------------------------

### FileController Interface

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

This section documents the FileController interface for handling file control operations like PRAGMA commands.

```APIDOC
## FileController.FileControl

### Description
Handles file control operations. For SQLITE_FCNTL_PRAGMA operations, pragmaName contains the pragma name (e.g., "litestream_time") and pragmaValue contains the pragma value (nil for queries). Returns the result string (for queries) and any error.

### Method
FileControl

### Parameters
- **op** (int) - Required - The file control operation code.
- **pragmaName** (string) - Required - The pragma name (for SQLITE_FCNTL_PRAGMA).
- **pragmaValue** (*string) - Optional - The pragma value (nil for queries).

### Returns
- **string** - The result string (for queries).
- **error** - Any error encountered.
```

--------------------------------

### Retrieve dataset rows with sqlitehttpcli

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfshttp

Execute a SELECT query to fetch a limited number of rows from the remote dataset.

```bash
# get 10 rows from the dataset
./sqlitehttpcli -url 'https://www.sanford.io/demo.db' -query "select * from csv limit 10"
row: [BOPQ.S06AC000000000A 1971.06 426  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
row: [BOPQ.S06AC000000000A 1971.09 435  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
row: [BOPQ.S06AC000000000A 1971.12 360  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
row: [BOPQ.S06AC000000000A 1972.03 417  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
row: [BOPQ.S06AC000000000A 1972.06 528  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
row: [BOPQ.S06AC000000000A 1972.09 471  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
row: [BOPQ.S06AC000000000A 1972.12 437  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
row: [BOPQ.S06AC000000000A 1973.03 607  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
row: [BOPQ.S06AC000000000A 1973.06 666  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
row: [BOPQ.S06AC000000000A 1973.09 578  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
```

--------------------------------

### Register sqlite3vfshttp VFS and open read-only SQLite connection

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfshttp

Registers the sqlite3vfshttp VFS and opens a read-only SQLite connection over HTTP. Requires a URL to a database hosted on a server supporting HTTP range requests. The connection string uses the vfs=httpvfs parameter and mode=ro.

```go
	vfs := sqlite3vfshttp.New(*url)

	err := sqlite3vfs.RegisterVFS("httpvfs", vfs)
	if err != nil {
		log.Fatalf("register vfs err: %s", err)
	}

	db, err := sql.Open("sqlite3", "not_a_read_name.db?vfs=httpvfs&mode=ro")
	if err != nil {
		log.Fatalf("open db err: %s", err)
	}

```

--------------------------------

### type File

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Represents a file interface for VFS operations.

```APIDOC
## type File

### Description
Represents a file interface for VFS operations.

### Methods
- **Close() error** - Closes the file.
- **ReadAt(p []byte, off int64) (n int, err error)** - Reads len(p) bytes into p starting at offset off. Returns the number of bytes read and any error. If n < len(p), SQLITE_IOERR_SHORT_READ will be returned to sqlite.
- **WriteAt(p []byte, off int64) (n int, err error)** - Writes len(p) bytes from p to the underlying data stream at offset off. Returns the number of bytes written and any error. WriteAt must return a non-nil error if it returns n < len(p).
- **Truncate(size int64) error** - Truncates the file to the given size.
- **Sync(flag SyncType) error** - Synchronizes the file.
- **FileSize() (int64, error)** - Returns the file size.
```

--------------------------------

### HttpVFS Access method

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfshttp

Checks access permissions for a file within the VFS.

```go
func (vfs *HttpVFS) Access(name string, flag sqlite3vfs.AccessFlag) (bool, error)
```

--------------------------------

### DeviceCharacteristic Constants

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Constants for device characteristics, such as atomic write capabilities and power-safe overwrite, as defined by SQLite.

```go
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
)
```

--------------------------------

### HttpVFS Delete method

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfshttp

Deletes a file from the VFS.

```go
func (vfs *HttpVFS) Delete(name string, dirSync bool) error
```

--------------------------------

### ExtendedVFSv1 Interface

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Extends the VFS interface with Randomness, Sleep, and CurrentTime methods for advanced VFS implementations.

```go
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
}
```

--------------------------------

### LockType String method

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Method to convert a LockType to its string representation.

```go
func (lt LockType) String() string
```

--------------------------------

### type DeviceCharacteristic

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Represents device characteristics for VFS operations.

```APIDOC
## type DeviceCharacteristic

### Description
Represents device characteristics for VFS operations.

### Constants
- **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
```

--------------------------------

### Filter dataset rows with sqlitehttpcli

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfshttp

Execute a SELECT query with a WHERE clause to filter results based on specific criteria.

```bash
# get 10 rows where the period is after 2010
$ ./sqlitehttpcli -url 'https://www.sanford.io/demo.db' -query "select * from csv where period > '2010' limit 10"
row: [BOPQ.S06AC000000000A 2010.03 17463  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
row: [BOPQ.S06AC000000000A 2010.06 17260  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
row: [BOPQ.S06AC000000000A 2010.09 15419  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
row: [BOPQ.S06AC000000000A 2010.12 17088  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
row: [BOPQ.S06AC000000000A 2011.03 18516  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
row: [BOPQ.S06AC000000000A 2011.06 18835  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
row: [BOPQ.S06AC000000000A 2011.09 16390  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
row: [BOPQ.S06AC000000000A 2011.12 18748  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
row: [BOPQ.S06AC000000000A 2012.03 18477  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
row: [BOPQ.S06AC000000000A 2012.06 18270  F Dollars 6 Balance of Payments - BOP BPM6 Quarterly, Balance of payments major components Actual]
```

--------------------------------

### HttpVFS struct definition

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfshttp

The HttpVFS struct defines the configuration for the VFS, including the base URL, cache handler, and HTTP round tripper.

```go
type HttpVFS struct {
	URL          string
	CacheHandler httpreadat.CacheHandler
	RoundTripper http.RoundTripper
}
```

--------------------------------

### OpenFlag type and constants

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Defines the OpenFlag integer type and its constants for file open flags, including read-only, read-write, create, delete-on-close, exclusive, URI, memory, and various database/journal flags.

```go
type OpenFlag int
```

```go
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
)
```

--------------------------------

### func RegisterVFS

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

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

```APIDOC
## func RegisterVFS

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

### Method
N/A

### Endpoint
N/A

### Parameters
#### Parameters
- **name** (string) - Required - The unique name for the VFS.
- **vfs** (VFS) - Required - The VFS implementation to register.
- **opts** (...Option) - Optional - Additional options for the VFS registration.

### Request Example
N/A

### Response
#### Success Response
- **error** (error) - Returns an error if registration fails.

#### Response Example
N/A
```

--------------------------------

### SyncType type and constants

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Defines the SyncType integer type and its constants for sync modes: SyncNormal, SyncFull, SyncDataOnly.

```go
type SyncType int
```

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

--------------------------------

### DeviceCharacteristic Type Definition

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Defines the DeviceCharacteristic integer type for device capabilities.

```go
type DeviceCharacteristic int
```

--------------------------------

### SQLite Error Code Variables

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Defines package-level variables for SQLite error codes, each as a sqliteError with a numeric code and message. These are used to return errors from VFS implementations.

```go
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"}
)
```

--------------------------------

### AccessFlag Type Definition

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Defines the AccessFlag integer type used for file access checks.

```go
type AccessFlag int
```

--------------------------------

### type AccessFlag

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Represents access flags used in VFS operations.

```APIDOC
## type AccessFlag

### Description
Represents access flags used in VFS operations.

### Constants
- **AccessExists** (AccessFlag) - Does the file exist?
- **AccessReadWrite** (AccessFlag) - Is the file both readable and writeable?
- **AccessRead** (AccessFlag) - Is the file readable?
```

--------------------------------

### type ExtendedVFSv1

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Extends the VFS interface with additional methods for randomness, sleep, and current time.

```APIDOC
## type ExtendedVFSv1

### Description
Extends the VFS interface with additional methods for randomness, sleep, and current time.

### Methods
- **Randomness(n []byte) int** - Populates n with pseudo-random data. Returns the number of bytes of randomness obtained.
- **Sleep(d time.Duration)** - Sleep for duration.
- **CurrentTime() time.Time** - Returns the current time.
```

--------------------------------

### LockType type and constants

Source: https://pkg.go.dev/github.com/psanford/sqlite3vfs

Defines the LockType integer type and its constants for lock levels: LockNone, LockShared, LockReserved, LockPending, LockExclusive. Referenced from SQLite C documentation.

```go
type LockType int
```

```go
const (
	LockNone      LockType = 0
	LockShared    LockType = 1
	LockReserved  LockType = 2
	LockPending   LockType = 3
	LockExclusive LockType = 4
)
```
Tokens:
Raw