github.com/ncruces/go-sqlite3@v0.15.1-0.20240520133447-53eef1510ff0/vfs/README.md (about)

     1  # Go SQLite VFS API
     2  
     3  This package implements the SQLite [OS Interface](https://sqlite.org/vfs.html) (aka VFS).
     4  
     5  It replaces the default SQLite VFS with a **pure Go** implementation,
     6  and exposes [interfaces](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs#VFS)
     7  that should allow you to implement your own custom VFSes.
     8  
     9  Since it is a from scratch reimplementation,
    10  there are naturally some ways it deviates from the original.
    11  
    12  The main differences are [file locking](#file-locking) and [WAL mode](#write-ahead-logging) support.
    13  
    14  ### File Locking
    15  
    16  POSIX advisory locks, which SQLite uses on Unix, are
    17  [broken by design](https://github.com/sqlite/sqlite/blob/b74eb0/src/os_unix.c#L1073-L1161).
    18  
    19  On Linux and macOS, this module uses
    20  [OFD locks](https://www.gnu.org/software/libc/manual/html_node/Open-File-Description-Locks.html)
    21  to synchronize access to database files.
    22  OFD locks are fully compatible with POSIX advisory locks.
    23  
    24  This module can also use
    25  [BSD locks](https://man.freebsd.org/cgi/man.cgi?query=flock&sektion=2),
    26  albeit with reduced concurrency (`BEGIN IMMEDIATE` behaves like `BEGIN EXCLUSIVE`).
    27  On BSD, macOS, and illumos, BSD locks are fully compatible with POSIX advisory locks;
    28  on Linux and z/OS, they are fully functional, but incompatible;
    29  elsewhere, they are very likely broken.
    30  BSD locks are the default on BSD and illumos,
    31  but you can opt into them with the `sqlite3_flock` build tag.
    32  
    33  On Windows, this module uses `LockFileEx` and `UnlockFileEx`,
    34  like SQLite.
    35  
    36  Otherwise, file locking is not supported, and you must use
    37  [`nolock=1`](https://sqlite.org/uri.html#urinolock)
    38  (or [`immutable=1`](https://sqlite.org/uri.html#uriimmutable))
    39  to open database files.
    40  To use the [`database/sql`](https://pkg.go.dev/database/sql) driver
    41  with `nolock=1` you must disable connection pooling by calling
    42  [`db.SetMaxOpenConns(1)`](https://pkg.go.dev/database/sql#DB.SetMaxOpenConns).
    43  
    44  You can use [`vfs.SupportsFileLocking`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs#SupportsFileLocking)
    45  to check if your build supports file locking.
    46  
    47  ### Write-Ahead Logging
    48  
    49  On 64-bit Linux and macOS, this module uses `mmap` to implement
    50  [shared-memory for the WAL-index](https://sqlite.org/wal.html#implementation_of_shared_memory_for_the_wal_index),
    51  like SQLite.
    52  
    53  To allow `mmap` to work, each connection needs to reserve up to 4GB of address space.
    54  To limit the address space each connection reserves,
    55  use [`WithMemoryLimitPages`](../tests/testcfg/testcfg.go).
    56  
    57  Otherwise, [WAL support is limited](https://sqlite.org/wal.html#noshm),
    58  and `EXCLUSIVE` locking mode must be set to create, read, and write WAL databases.
    59  To use `EXCLUSIVE` locking mode with the
    60  [`database/sql`](https://pkg.go.dev/database/sql) driver
    61  you must disable connection pooling by calling
    62  [`db.SetMaxOpenConns(1)`](https://pkg.go.dev/database/sql#DB.SetMaxOpenConns).
    63  
    64  You can use [`vfs.SupportsSharedMemory`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs#SupportsSharedMemory)
    65  to check if your build supports shared memory.
    66  
    67  ### Batch-Atomic Write
    68  
    69  On 64-bit Linux, this module supports [batch-atomic writes](https://sqlite.org/cgi/src/technote/714)
    70  on the F2FS filesystem.
    71  
    72  ### Build Tags
    73  
    74  The VFS can be customized with a few build tags:
    75  - `sqlite3_flock` forces the use of BSD locks; it can be used on z/OS to enable locking,
    76    and elsewhere to test BSD locks.
    77  - `sqlite3_nosys` prevents importing [`x/sys`](https://pkg.go.dev/golang.org/x/sys);
    78    disables locking _and_ shared memory on all platforms.
    79  - `sqlite3_noshm` disables shared memory on all platforms.
    80  
    81  > [!IMPORTANT]
    82  > The default configuration of this package is compatible with
    83  > the standard [Unix and Windows SQLite VFSes](https://sqlite.org/vfs.html#multiple_vfses);
    84  > `sqlite3_flock` is compatible with the [`unix-flock` VFS](https://sqlite.org/compile.html#enable_locking_style).
    85  > If incompatible file locking is used, accessing databases concurrently with _other_ SQLite libraries
    86  > will eventually corrupt data.