sqlite3/vfs/README.md

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, macOS, and illumos, these locks are fully compatible with POSIX advisory locks; on Linux and z/OS, they are fully functional, but incompatible with POSIX advisory locks. However, concurrency is always reduced with BSD locks (BEGIN IMMEDIATE behaves the same as BEGIN EXCLUSIVE). You can opt into BSD locks with the sqlite3_flock build tag.

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 build 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 with BSD locks, 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 is disabled.

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 with the F2FS filesystem.

Build Tags

The VFS can be customized with a few build tags:

• sqlite3_flock forces the use of BSD locks; it can be used on z/OS for locking support, and elsewhere to test the BSD locks.
• sqlite3_nosys prevents importing x/sys; disables locking and shared memory on all platforms.
• sqlite3_noshm disables shared memory on all platforms.

Caution

If file locking is incompatible with POSIX advisory locks, accessing databases concurrently with this package and other SQLite implementations is unsafe, and will eventually corrupt data. This will only be the case if you explicitly opt into BSD locks with sqlite3_flock. The SQLite unix-flock VFS is always compatible with sqlite3_flock.