Docs.

Author: ncruces

README.md

@@ -65,17 +65,20 @@ db.QueryRow(`SELECT sqlite_version()`).Scan(&version)
 This module replaces the SQLite [OS Interface](https://sqlite.org/vfs.html)
 (aka VFS) with a [pure Go](vfs/) implementation,
 which has advantages and disadvantages.
-
 Read more about the Go VFS design [here](vfs/README.md).
 
+Because each database connection executes within a Wasm sandboxed environment,
+memory usage will be higher than alternatives.
+
 ### Testing
 
 This project aims for [high test coverage](https://github.com/ncruces/go-sqlite3/wiki/Test-coverage-report).
 It also benefits greatly from [SQLite's](https://sqlite.org/testing.html) and
-[wazero's](https://tetrate.io/blog/introducing-wazero-from-tetrate/#:~:text=Rock%2Dsolid%20test%20approach) thorough testing.
+[wazero's](https://tetrate.io/blog/introducing-wazero-from-tetrate/#:~:text=Rock%2Dsolid%20test%20approach)
+thorough testing.
 
 Every commit is [tested](https://github.com/ncruces/go-sqlite3/wiki/Support-matrix) on
-Linux (amd64/arm64/386/riscv64/ppc64le/s390x), macOS (amd64/arm64),
+Linux (amd64/arm64/386/riscv64/ppc64le/s390x), macOS (arm64/amd64),
 Windows (amd64), FreeBSD (amd64/arm64), OpenBSD (amd64), NetBSD (amd64/arm64),
 DragonFly BSD (amd64), illumos (amd64), and Solaris (amd64).
 
@@ -84,12 +87,21 @@ The Go VFS is tested by running SQLite's
 
 ### Performance
 
-Perfomance of the [`database/sql`](https://pkg.go.dev/database/sql) driver is
+Performance of the [`database/sql`](https://pkg.go.dev/database/sql) driver is
 [competitive](https://github.com/cvilsmeier/go-sqlite-bench) with alternatives.
 
-The Wasm and VFS layers are also tested by running SQLite's
+The Wasm and VFS layers are also benchmarked by running SQLite's
 [speedtest1](https://github.com/sqlite/sqlite/blob/master/test/speedtest1.c).
 
+### Concurrency
+
+This module behaves similarly to SQLite in [multi-thread](https://sqlite.org/threadsafe.html) mode:
+it is goroutine-safe, provided that no single database connection, or object derived from it,
+is used concurrently by multiple goroutines.
+
+The [`database/sql`](https://pkg.go.dev/database/sql) driver is safe to use concurrently,
+according to its documentation.
+
 ### FAQ, issues, new features
 
 For questions, please see [Discussions](https://github.com/ncruces/go-sqlite3/discussions/categories/q-a).

vfs/README.md

@@ -6,22 +6,30 @@ It replaces the default SQLite VFS with a **pure Go** implementation,
 and exposes [interfaces](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs#VFS)
 that should allow you to implement your own [custom VFSes](#custom-vfses).
 
-Since it is a from scratch reimplementation,
+See the [support matrix](https://github.com/ncruces/go-sqlite3/wiki/Support-matrix)
+for the list of supported OS and CPU architectures.
+
+Since this is a from scratch reimplementation,
 there are naturally some ways it deviates from the original.
+It's also not as battle tested as the original.
 
-The main differences are [file locking](#file-locking) and [WAL mode](#write-ahead-logging) support.
+The main differences to be aware of are
+[file locking](#file-locking) and
+[WAL mode](#write-ahead-logging) support.
 
 ### File Locking
 
-POSIX advisory locks, which SQLite uses on Unix, are
-[broken by design](https://github.com/sqlite/sqlite/blob/b74eb0/src/os_unix.c#L1073-L1161).
+POSIX advisory locks,
+which SQLite uses on [Unix](https://github.com/sqlite/sqlite/blob/5d60f4/src/os_unix.c#L13-L14),
+are [broken by design](https://github.com/sqlite/sqlite/blob/5d60f4/src/os_unix.c#L1074-L1162).
 Instead, on Linux and macOS, this package uses
 [OFD locks](https://www.gnu.org/software/libc/manual/html_node/Open-File-Description-Locks.html)
 to synchronize access to database files.
 
 This package can also use
 [BSD locks](https://man.freebsd.org/cgi/man.cgi?query=flock&sektion=2),
-albeit with reduced concurrency (`BEGIN IMMEDIATE` behaves like `BEGIN EXCLUSIVE`).
+albeit with reduced concurrency (`BEGIN IMMEDIATE` behaves like `BEGIN EXCLUSIVE`,
+[docs](https://sqlite.org/lang_transaction.html#immediate)).
 BSD locks are the default on BSD and illumos,
 but you can opt into them with the `sqlite3_flock` build tag.
 
@@ -44,11 +52,11 @@ to check if your build supports file locking.
 
 ### Write-Ahead Logging
 
-On Unix, this package may use `mmap` to implement
+On Unix, this package uses `mmap` to implement
 [shared-memory for the WAL-index](https://sqlite.org/wal.html#implementation_of_shared_memory_for_the_wal_index),
 like SQLite.
 
-On Windows, this package may use `MapViewOfFile`, like SQLite.
+On Windows, this package uses `MapViewOfFile`, like SQLite.
 
 You can also opt into a cross-platform, in-process, memory sharing implementation
 with the `sqlite3_dotlk` build tag.
@@ -63,6 +71,11 @@ you must disable connection pooling by calling
 You can use [`vfs.SupportsSharedMemory`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs#SupportsSharedMemory)
 to check if your build supports shared memory.
 
+### Blocking Locks
+
+On Windows and macOS, this package implements
+[Wal-mode blocking locks](https://sqlite.org/src/doc/tip/doc/wal-lock.md).
+
 ### Batch-Atomic Write
 
 On Linux, this package may support
@@ -94,8 +107,8 @@ The VFS can be customized with a few build tags:
 > [`unix-flock` VFS](https://sqlite.org/compile.html#enable_locking_style);
 > `sqlite3_dotlk` builds are compatible with the
 > [`unix-dotfile` VFS](https://sqlite.org/compile.html#enable_locking_style).
-> If incompatible file locking is used, accessing databases concurrently with
-> _other_ SQLite libraries will eventually corrupt data.
+> Accessing databases concurrently using incompatible implementations
+> will eventually corrupt data.
 
 ### Custom VFSes