Docs.

Author: ncruces

vfs/memdb/README.md

@@ -6,4 +6,7 @@ SQLite VFS in pure Go.
 It has some benefits over the C version:
 - the memory backing the database needs not be contiguous,
 - the database can grow/shrink incrementally without copying,
-- reader-writer concurrency is slightly improved.
+- reader-writer concurrency is slightly improved.
+
+[`memdb.TestDB`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs/memdb#TestDB)
+is the preferred way to setup an in-memory database for testing.

vfs/memdb/api.go

@@ -77,6 +77,21 @@ func Delete(name string) {
 // The database is automatically deleted when the test and all its subtests complete.
 // Returns a URI filename appropriate to call Open with.
 // Each subsequent call to TestDB returns a unique database.
+//
+//	func Test_something(t *testing.T) {
+//		t.Parallel()
+//		dsn := memdb.TestDB(t, url.Values{
+//			"_pragma": {"busy_timeout(1000)"},
+//		})
+//
+//		db, err := sql.Open("sqlite3", dsn)
+//		if err != nil {
+//			t.Fatal(err)
+//		}
+//		defer db.Close()
+//
+//		// ...
+//	}
 func TestDB(tb testing.TB, params ...url.Values) string {
 	tb.Helper()
 

vfs/mvcc/README.md

@@ -6,4 +6,10 @@ It has some benefits over the [`"memdb"`](../memdb/README.md) VFS:
 - panics do not corrupt a shared database,
 - single-writer not blocked by readers,
 - readers never block,
-- instant snapshots.
+- instant snapshots.
+
+[`mvcc.TestDB`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs/mvcc#TestDB)
+is the preferred way to setup an in-memory database for testing
+when you intend to leverage snapshots,
+e.g. to setup many independent copies of a database,
+such as one for each subtest.

vfs/mvcc/api.go

@@ -98,6 +98,21 @@ func TakeSnapshot(name string) Snapshot {
 // The database is automatically deleted when the test and all its subtests complete.
 // Returns a URI filename appropriate to call Open with.
 // Each subsequent call to TestDB returns a unique database.
+//
+//	func Test_something(t *testing.T) {
+//		t.Parallel()
+//		dsn := mvcc.TestDB(t, snapshot, url.Values{
+//			"_pragma": {"busy_timeout(1000)"},
+//		})
+//
+//		db, err := sql.Open("sqlite3", dsn)
+//		if err != nil {
+//			t.Fatal(err)
+//		}
+//		defer db.Close()
+//
+//		// ...
+//	}
 func TestDB(tb testing.TB, snapshot Snapshot, params ...url.Values) string {
 	tb.Helper()