# README
Go SQLite VFS API
This package implements the SQLite OS Interface (aka VFS).
It replaces the default SQLite VFS with a pure Go implementation, and exposes interfaces that should allow you to implement your own custom VFSes.
Since it is a from scratch reimplementation, there are naturally some ways it deviates from the original.
The main differences are file locking and WAL mode support.
File Locking
POSIX advisory locks, which SQLite uses on Unix, are broken by design.
On Linux and macOS, this module uses OFD locks to synchronize access to database files. OFD locks are fully compatible with POSIX advisory locks.
This module can also use
BSD locks,
albeit with reduced concurrency (BEGIN IMMEDIATE behaves like BEGIN EXCLUSIVE).
On BSD, macOS, and illumos, BSD locks are fully compatible with POSIX advisory locks;
on Linux and z/OS, they are fully functional, but incompatible;
elsewhere, they are very likely broken.
BSD locks are the default on BSD and illumos,
but you can opt into them with the sqlite3_flock build tag.
On Windows, this module uses LockFileEx and UnlockFileEx,
like SQLite.
Otherwise, file locking is not supported, and you must use
nolock=1
(or immutable=1)
to open database files.
To use the database/sql driver
with nolock=1 you must disable connection pooling by calling
db.SetMaxOpenConns(1).
You can use vfs.SupportsFileLocking
to check if your build supports file locking.
Write-Ahead Logging
On 64-bit Unix, this module uses mmap to implement
shared-memory for the WAL-index,
like SQLite.
To allow mmap to work, each connection needs to reserve up to 4GB of address space.
To limit the address space each connection reserves,
use WithMemoryLimitPages.
With BSD locks
a WAL database can only be accessed by a single proccess.
Other processes that attempt to access a database locked with BSD locks,
will fail with the SQLITE_PROTOCOL error code.
Otherwise, WAL support is limited,
and EXCLUSIVE locking mode must be set to create, read, and write WAL databases.
To use EXCLUSIVE locking mode with the
database/sql driver
you must disable connection pooling by calling
db.SetMaxOpenConns(1).
You can use vfs.SupportsSharedMemory
to check if your build supports shared memory.
Batch-Atomic Write
On 64-bit Linux, this module supports batch-atomic writes on the F2FS filesystem.
Build Tags
The VFS can be customized with a few build tags:
sqlite3_flockforces the use of BSD locks; it can be used on z/OS to enable locking, and elsewhere to test BSD locks.sqlite3_nosysprevents importingx/sys; disables locking and shared memory on all platforms.sqlite3_noshmdisables shared memory on all platforms.
[!IMPORTANT] The default configuration of this package is compatible with the standard Unix and Windows SQLite VFSes;
sqlite3_flockbuilds are compatible with theunix-flockVFS. If incompatible file locking is used, accessing databases concurrently with other SQLite libraries will eventually corrupt data.