From ea860e407d08c8b42fb4bb9526660b78bdb8c04c Mon Sep 17 00:00:00 2001
From: Nuno Cruces <ncruces@users.noreply.github.com>
Date: Wed, 1 Oct 2025 11:00:13 +0100
Subject: [PATCH] Docs.

---
 vfs/memdb/README.md |  5 ++++-
 vfs/memdb/api.go    | 15 +++++++++++++++
 vfs/mvcc/README.md  |  8 +++++++-
 vfs/mvcc/api.go     | 15 +++++++++++++++
 4 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/vfs/memdb/README.md b/vfs/memdb/README.md
index 2e2611b..e37db1b 100644
--- a/vfs/memdb/README.md
+++ b/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.
\ No newline at end of file
+- 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.
\ No newline at end of file
diff --git a/vfs/memdb/api.go b/vfs/memdb/api.go
index e61ab76..a128198 100644
--- a/vfs/memdb/api.go
+++ b/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()
 
diff --git a/vfs/mvcc/README.md b/vfs/mvcc/README.md
index 557dccd..aa32dfb 100644
--- a/vfs/mvcc/README.md
+++ b/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.
\ No newline at end of file
+- 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.
\ No newline at end of file
diff --git a/vfs/mvcc/api.go b/vfs/mvcc/api.go
index d8956fa..5f20e53 100644
--- a/vfs/mvcc/api.go
+++ b/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()