3.4 KiB
Go SQLite VFS API
This package implements the SQLite OS Interface (aka VFS).
It replaces the default SQLite VFS with a pure Go implementation.
It also 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.
On BSD Unixes, this module uses
BSD locks.
On BSD, these locks are fully compatible with POSIX advisory locks.
However, concurrency is reduced with BSD locks
(BEGIN IMMEDIATE behaves the same as BEGIN EXCLUSIVE).
On Windows, this module uses LockFileEx and UnlockFileEx,
like SQLite.
On all other platforms, 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 platform supports file locking.
Write-Ahead Logging
On 64-bit Linux and macOS, 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 amount of address space each connection needs,
use WithMemoryLimitPages.
On Windows and BSD, WAL support is
limited.
EXCLUSIVE locking mode can 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).
On all other platforms, where file locking is not supported, WAL mode does not work.
You can use vfs.SupportsSharedMemory
to check if your platform supports shared memory.
Batch-Atomic Write
On 64-bit Linux, this module supports batch-atomic writes with 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 macOS to test the BSD locking implementation.sqlite3_nosysprevents importingx/sys; disables locking and shared memory on all platforms.sqlite3_noshmdisables shared memory on all platforms.