dirsql 0.2.9__tar.gz → 0.3.0__tar.gz

{dirsql-0.2.9 → dirsql-0.3.0}/Cargo.lock

@@ -73,6 +73,18 @@ version = "1.0.102"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
 
+[[package]]
+name = "arrayref"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76a2e8124351fda1ef8aaaa3bbd7ebbcb486bbcd4225aca0aa0d84bb2db8fecb"
+
+[[package]]
+name = "arrayvec"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7c02d123df017efcdfbd739ef81735b36c5ba83ec3c59c80a9d7ecc718f92e50"
+
 [[package]]
 name = "assert_cmd"
 version = "2.2.1"
@@ -176,6 +188,20 @@ version = "2.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
 
+[[package]]
+name = "blake3"
+version = "1.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4d2d5991425dfd0785aed03aedcf0b321d61975c9b5b3689c774a2610ae0b51e"
+dependencies = [
+ "arrayref",
+ "arrayvec",
+ "cc",
+ "cfg-if",
+ "constant_time_eq",
+ "cpufeatures",
+]
+
 [[package]]
 name = "bstr"
 version = "1.12.1"
@@ -300,6 +326,12 @@ version = "1.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
 
+[[package]]
+name = "constant_time_eq"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d52eff69cd5e647efe296129160853a42795992097e8af39800e1060caeea9b"
+
 [[package]]
 name = "convert_case"
 version = "0.11.0"
@@ -325,6 +357,15 @@ version = "0.8.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
 
+[[package]]
+name = "cpufeatures"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b2a41393f66f16b0823bb79094d54ac5fbd34ab292ddafb9a0456ac9f87d201"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "criterion"
 version = "0.5.1"
@@ -441,6 +482,7 @@ version = "0.2.7"
 dependencies = [
  "assert_cmd",
  "axum",
+ "blake3",
  "clap",
  "criterion",
  "csv",
@@ -480,7 +522,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.2.9"
+version = "0.3.0"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.2.9 → dirsql-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.2.9
+Version: 0.3.0
 Requires-Dist: pytest>=8 ; extra == 'dev'
 Requires-Dist: pytest-describe>=2 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'

{dirsql-0.2.9 → dirsql-0.3.0}/docs/.vitepress/config.ts

@@ -32,6 +32,7 @@ export default defineConfig({
           { text: 'Defining Tables', link: '/guide/tables' },
           { text: 'Querying', link: '/guide/querying' },
           { text: 'File Watching', link: '/guide/watching' },
+          { text: 'Persistence', link: '/guide/persistence' },
           { text: 'Async API', link: '/guide/async' },
           { text: 'Command-Line Interface', link: '/guide/cli' },
           { text: 'Collaboration with CRDTs', link: '/guide/crdt' }

{dirsql-0.2.9 → dirsql-0.3.0}/docs/guide/config.md

@@ -169,6 +169,20 @@ The `ignore` list skips files and directories entirely (not even scanned):
 ignore = ["node_modules/**", ".git/**", "*.pyc", "__pycache__/**"]
 ```
 
+The top-level `.dirsql/` directory is always excluded, whether you list it or not -- it is a reserved namespace for `dirsql`'s own metadata (see [Persistence](./persistence.md)).
+
+## Persistence
+
+Set `persist = true` to keep the SQLite database on disk between runs instead of rebuilding from scratch on every startup:
+
+```toml
+[dirsql]
+persist = true
+# persist_path = ".dirsql/cache.db"   # optional; this is the default
+```
+
+See [Persistence](./persistence.md) for the full reconcile algorithm, storage layout, and limitations.
+
 ## Strict Mode
 
 By default, extra keys in file content are ignored and missing keys become NULL. Enable strict mode to error on mismatches:

dirsql-0.3.0/docs/guide/persistence.md

@@ -0,0 +1,177 @@
+# Persistence
+
+By default `dirsql` keeps its SQLite database in memory and rebuilds it from scratch every time the process starts. For large directories this can take seconds to minutes -- nearly all of which is spent re-parsing files that haven't changed since the previous run.
+
+Persistence stores the SQLite database on disk so that subsequent startups only re-parse the files that have actually changed.
+
+::: tip Same answers, faster startup
+The rows returned by `query()` after a persistent startup are equivalent to those produced by a from-scratch rebuild. Persistence is a startup-time optimization, not a correctness compromise. The reconcile algorithm is the same one `git status` uses to decide which files have changed since the last index write.
+:::
+
+## Quick start
+
+::: code-group
+
+```toml [.dirsql.toml]
+[dirsql]
+persist = true
+```
+
+```python [Python]
+from dirsql import DirSQL
+
+db = DirSQL("./my-project", tables=[...], persist=True)
+await db.ready()
+```
+
+```rust [Rust]
+use dirsql::DirSQL;
+
+let db = DirSQL::builder()
+    .root("./my-project")
+    .tables(vec![/* ... */])
+    .persist(true)
+    .build()?;
+```
+
+```typescript [TypeScript]
+import { DirSQL } from "dirsql";
+
+const db = new DirSQL({ root: "./my-project", tables: [/* ... */], persist: true });
+await db.ready;
+```
+
+:::
+
+That's it. The first run writes the database to `./my-project/.dirsql/cache.db`. Every subsequent startup uses the cache.
+
+## Configuration
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `persist` | boolean | `false` | Enable persistent on-disk storage. |
+| `persist_path` (Python, Rust) / `persistPath` (TypeScript) | string | `<root>/.dirsql/cache.db` | Override the database file path. Ignored when `persist` is `false`. |
+
+The default location keeps the cache alongside the data it indexes, which means it follows the project around (clone, copy, move) without extra setup. Override `persist_path` if you want the cache somewhere else -- a CI cache directory, a tmpfs mount, an XDG cache dir, etc.
+
+::: code-group
+
+```toml [.dirsql.toml]
+[dirsql]
+persist = true
+persist_path = "/var/cache/dirsql/myproject.db"
+```
+
+```python [Python]
+db = DirSQL(
+    "./my-project",
+    tables=[...],
+    persist=True,
+    persist_path="/var/cache/dirsql/myproject.db",
+)
+```
+
+```rust [Rust]
+let db = DirSQL::builder()
+    .root("./my-project")
+    .tables(vec![/* ... */])
+    .persist(true)
+    .persist_path("/var/cache/dirsql/myproject.db")
+    .build()?;
+```
+
+```typescript [TypeScript]
+const db = new DirSQL({
+  root: "./my-project",
+  tables: [/* ... */],
+  persist: true,
+  persistPath: "/var/cache/dirsql/myproject.db",
+});
+```
+
+:::
+
+## The `.dirsql/` directory
+
+`dirsql` reserves the top-level `.dirsql/` directory inside every scanned root. It is **unconditionally excluded from the directory walk**, whether persistence is enabled or not. This means:
+
+- The default cache path `<root>/.dirsql/cache.db` cannot accidentally be ingested as a data file.
+- You can place additional `dirsql`-related files in `.dirsql/` (e.g. a project-local config snapshot) without them being parsed.
+- You should not put your own data files in `.dirsql/` -- they will be silently ignored.
+
+If you persist into `.dirsql/`, add it to your `.gitignore`:
+
+```
+.dirsql/
+```
+
+The cache file should never be committed -- it is reproducible from the source tree and frequently large.
+
+## How the startup reconcile works
+
+When a persistent cache exists, `dirsql` does not blindly trust it. On startup it:
+
+1. **Checks compatibility metadata.** If the cached `dirsql` version, schema version, glob configuration, parser versions, or canonical root path differs from the current build, the cache is wiped and rebuilt from scratch.
+2. **Walks the tree and stats every matching file.** This is metadata-only -- no file contents are read.
+3. **For each file, compares the live `(size, mtime, ctime, inode, dev)` tuple against the cached row:**
+   - **Trust the cache** when every field matches *and* the file's mtime is older than the cache's snapshot time (outside the racy window).
+   - **Hash-confirm** when the tuple matches but the file's mtime falls inside the racy window. `dirsql` reads and hashes the file; if the hash matches the cached hash, the cache is trusted.
+   - **Re-parse** when any field of the tuple differs.
+4. **Deletes** rows for files that were in the cache but are no longer on disk.
+5. **Inserts** rows for files that are on disk but were not in the cache.
+
+This is the same algorithm `git status` uses to decide which files have changed since the last index write. The "racy window" handling is what closes the gap when a file is modified within the same filesystem-timestamp resolution as the cache write.
+
+## When `dirsql` does a full rebuild
+
+Any of the following will cause the cache to be discarded and rebuilt from scratch on the next startup:
+
+- The `dirsql` library was upgraded between runs.
+- The glob configuration changed (a new table, a removed table, a modified glob, a changed `ignore` list).
+- A built-in parser version changed (this generally only happens on `dirsql` upgrades).
+- The cache was written for a different root directory than the one currently configured.
+- The internal schema of the cache changed (i.e. you upgraded `dirsql` across a schema version bump).
+
+Full rebuilds take exactly as long as a non-persistent startup -- there is no penalty for them, only a missed optimization.
+
+## Limitations
+
+### Network filesystems
+
+NFS, SMB/CIFS, and similar network filesystems cache file attributes on the client and can return stale `stat` results. Persistent mode is **not supported** on network filesystems and may produce stale rows. Use in-memory mode (the default) if your `root` lives on a network mount.
+
+### The mtime-preservation edge case
+
+Racy-stat detection misses changes only when **all** of the following are true:
+
+- A file's contents are modified.
+- The file's size after modification is identical to its size before.
+- The file's `mtime` is externally reset to a value older than the cache's snapshot time (e.g. via `touch -r` or a backup-restore tool that preserves mtime).
+
+If you cannot tolerate this edge case, disable persistence (`persist = false`). This is the same trade-off `git` makes with `core.trustctime` / `core.checkStat`.
+
+### Single writer
+
+Only one `dirsql` process should write to a given cache file at a time. Multiple read-only processes can query the same file safely once the writer finishes the initial reconcile. Coordinated multi-writer access is not supported in v0.3.0.
+
+## Inspecting the cache
+
+The persistent database is a normal SQLite file. You can open it with any SQLite client:
+
+```bash
+sqlite3 .dirsql/cache.db
+```
+
+```sql
+.tables
+-- comments  documents  metrics  _dirsql_files  _dirsql_meta
+
+SELECT * FROM _dirsql_meta;
+-- schema_version    | 1
+-- dirsql_version    | 0.3.0
+-- glob_config_hash  | <hex>
+-- parser_versions   | {"json":"1","jsonl":"1","csv":"1",...}
+-- root_canonical    | /home/alice/my-project
+```
+
+The `_dirsql_files` and `_dirsql_meta` tables are managed by `dirsql`. Do not modify them by hand -- on the next startup, `dirsql` will detect the inconsistency and rebuild from scratch.

{dirsql-0.2.9 → dirsql-0.3.0}/packages/python/Cargo.toml

@@ -4,7 +4,7 @@ name = "dirsql-py-ext"
 # pypi/maturin handler can rewrite it via `write-version` before
 # `maturin build`. `pyproject.toml` declares `dynamic = ["version"]`
 # and maturin reads this field. Mirrors `packages/rust/Cargo.toml`.
-version = "0.2.9"
+version = "0.3.0"
 edition.workspace = true
 publish = false
 readme = "README.md"

{dirsql-0.2.9 → dirsql-0.3.0}/packages/python/docs/.vitepress/config.ts

@@ -32,6 +32,7 @@ export default defineConfig({
           { text: 'Defining Tables', link: '/guide/tables' },
           { text: 'Querying', link: '/guide/querying' },
           { text: 'File Watching', link: '/guide/watching' },
+          { text: 'Persistence', link: '/guide/persistence' },
           { text: 'Async API', link: '/guide/async' },
           { text: 'Command-Line Interface', link: '/guide/cli' },
           { text: 'Collaboration with CRDTs', link: '/guide/crdt' }

{dirsql-0.2.9/packages/rust → dirsql-0.3.0/packages/python}/docs/guide/config.md

@@ -169,6 +169,20 @@ The `ignore` list skips files and directories entirely (not even scanned):
 ignore = ["node_modules/**", ".git/**", "*.pyc", "__pycache__/**"]
 ```
 
+The top-level `.dirsql/` directory is always excluded, whether you list it or not -- it is a reserved namespace for `dirsql`'s own metadata (see [Persistence](./persistence.md)).
+
+## Persistence
+
+Set `persist = true` to keep the SQLite database on disk between runs instead of rebuilding from scratch on every startup:
+
+```toml
+[dirsql]
+persist = true
+# persist_path = ".dirsql/cache.db"   # optional; this is the default
+```
+
+See [Persistence](./persistence.md) for the full reconcile algorithm, storage layout, and limitations.
+
 ## Strict Mode
 
 By default, extra keys in file content are ignored and missing keys become NULL. Enable strict mode to error on mismatches:

dirsql-0.3.0/packages/python/docs/guide/persistence.md

@@ -0,0 +1,177 @@
+# Persistence
+
+By default `dirsql` keeps its SQLite database in memory and rebuilds it from scratch every time the process starts. For large directories this can take seconds to minutes -- nearly all of which is spent re-parsing files that haven't changed since the previous run.
+
+Persistence stores the SQLite database on disk so that subsequent startups only re-parse the files that have actually changed.
+
+::: tip Same answers, faster startup
+The rows returned by `query()` after a persistent startup are equivalent to those produced by a from-scratch rebuild. Persistence is a startup-time optimization, not a correctness compromise. The reconcile algorithm is the same one `git status` uses to decide which files have changed since the last index write.
+:::
+
+## Quick start
+
+::: code-group
+
+```toml [.dirsql.toml]
+[dirsql]
+persist = true
+```
+
+```python [Python]
+from dirsql import DirSQL
+
+db = DirSQL("./my-project", tables=[...], persist=True)
+await db.ready()
+```
+
+```rust [Rust]
+use dirsql::DirSQL;
+
+let db = DirSQL::builder()
+    .root("./my-project")
+    .tables(vec![/* ... */])
+    .persist(true)
+    .build()?;
+```
+
+```typescript [TypeScript]
+import { DirSQL } from "dirsql";
+
+const db = new DirSQL({ root: "./my-project", tables: [/* ... */], persist: true });
+await db.ready;
+```
+
+:::
+
+That's it. The first run writes the database to `./my-project/.dirsql/cache.db`. Every subsequent startup uses the cache.
+
+## Configuration
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `persist` | boolean | `false` | Enable persistent on-disk storage. |
+| `persist_path` (Python, Rust) / `persistPath` (TypeScript) | string | `<root>/.dirsql/cache.db` | Override the database file path. Ignored when `persist` is `false`. |
+
+The default location keeps the cache alongside the data it indexes, which means it follows the project around (clone, copy, move) without extra setup. Override `persist_path` if you want the cache somewhere else -- a CI cache directory, a tmpfs mount, an XDG cache dir, etc.
+
+::: code-group
+
+```toml [.dirsql.toml]
+[dirsql]
+persist = true
+persist_path = "/var/cache/dirsql/myproject.db"
+```
+
+```python [Python]
+db = DirSQL(
+    "./my-project",
+    tables=[...],
+    persist=True,
+    persist_path="/var/cache/dirsql/myproject.db",
+)
+```
+
+```rust [Rust]
+let db = DirSQL::builder()
+    .root("./my-project")
+    .tables(vec![/* ... */])
+    .persist(true)
+    .persist_path("/var/cache/dirsql/myproject.db")
+    .build()?;
+```
+
+```typescript [TypeScript]
+const db = new DirSQL({
+  root: "./my-project",
+  tables: [/* ... */],
+  persist: true,
+  persistPath: "/var/cache/dirsql/myproject.db",
+});
+```
+
+:::
+
+## The `.dirsql/` directory
+
+`dirsql` reserves the top-level `.dirsql/` directory inside every scanned root. It is **unconditionally excluded from the directory walk**, whether persistence is enabled or not. This means:
+
+- The default cache path `<root>/.dirsql/cache.db` cannot accidentally be ingested as a data file.
+- You can place additional `dirsql`-related files in `.dirsql/` (e.g. a project-local config snapshot) without them being parsed.
+- You should not put your own data files in `.dirsql/` -- they will be silently ignored.
+
+If you persist into `.dirsql/`, add it to your `.gitignore`:
+
+```
+.dirsql/
+```
+
+The cache file should never be committed -- it is reproducible from the source tree and frequently large.
+
+## How the startup reconcile works
+
+When a persistent cache exists, `dirsql` does not blindly trust it. On startup it:
+
+1. **Checks compatibility metadata.** If the cached `dirsql` version, schema version, glob configuration, parser versions, or canonical root path differs from the current build, the cache is wiped and rebuilt from scratch.
+2. **Walks the tree and stats every matching file.** This is metadata-only -- no file contents are read.
+3. **For each file, compares the live `(size, mtime, ctime, inode, dev)` tuple against the cached row:**
+   - **Trust the cache** when every field matches *and* the file's mtime is older than the cache's snapshot time (outside the racy window).
+   - **Hash-confirm** when the tuple matches but the file's mtime falls inside the racy window. `dirsql` reads and hashes the file; if the hash matches the cached hash, the cache is trusted.
+   - **Re-parse** when any field of the tuple differs.
+4. **Deletes** rows for files that were in the cache but are no longer on disk.
+5. **Inserts** rows for files that are on disk but were not in the cache.
+
+This is the same algorithm `git status` uses to decide which files have changed since the last index write. The "racy window" handling is what closes the gap when a file is modified within the same filesystem-timestamp resolution as the cache write.
+
+## When `dirsql` does a full rebuild
+
+Any of the following will cause the cache to be discarded and rebuilt from scratch on the next startup:
+
+- The `dirsql` library was upgraded between runs.
+- The glob configuration changed (a new table, a removed table, a modified glob, a changed `ignore` list).
+- A built-in parser version changed (this generally only happens on `dirsql` upgrades).
+- The cache was written for a different root directory than the one currently configured.
+- The internal schema of the cache changed (i.e. you upgraded `dirsql` across a schema version bump).
+
+Full rebuilds take exactly as long as a non-persistent startup -- there is no penalty for them, only a missed optimization.
+
+## Limitations
+
+### Network filesystems
+
+NFS, SMB/CIFS, and similar network filesystems cache file attributes on the client and can return stale `stat` results. Persistent mode is **not supported** on network filesystems and may produce stale rows. Use in-memory mode (the default) if your `root` lives on a network mount.
+
+### The mtime-preservation edge case
+
+Racy-stat detection misses changes only when **all** of the following are true:
+
+- A file's contents are modified.
+- The file's size after modification is identical to its size before.
+- The file's `mtime` is externally reset to a value older than the cache's snapshot time (e.g. via `touch -r` or a backup-restore tool that preserves mtime).
+
+If you cannot tolerate this edge case, disable persistence (`persist = false`). This is the same trade-off `git` makes with `core.trustctime` / `core.checkStat`.
+
+### Single writer
+
+Only one `dirsql` process should write to a given cache file at a time. Multiple read-only processes can query the same file safely once the writer finishes the initial reconcile. Coordinated multi-writer access is not supported in v0.3.0.
+
+## Inspecting the cache
+
+The persistent database is a normal SQLite file. You can open it with any SQLite client:
+
+```bash
+sqlite3 .dirsql/cache.db
+```
+
+```sql
+.tables
+-- comments  documents  metrics  _dirsql_files  _dirsql_meta
+
+SELECT * FROM _dirsql_meta;
+-- schema_version    | 1
+-- dirsql_version    | 0.3.0
+-- glob_config_hash  | <hex>
+-- parser_versions   | {"json":"1","jsonl":"1","csv":"1",...}
+-- root_canonical    | /home/alice/my-project
+```
+
+The `_dirsql_files` and `_dirsql_meta` tables are managed by `dirsql`. Do not modify them by hand -- on the next startup, `dirsql` will detect the inconsistency and rebuild from scratch.

{dirsql-0.2.9 → dirsql-0.3.0}/packages/python/src/lib.rs

@@ -17,6 +17,7 @@ mod python {
     use pyo3::prelude::*;
     use pyo3::types::{PyDict, PyList};
     use std::collections::HashMap;
+    use std::path::PathBuf;
     use std::time::Duration;
 
     // -- Public PyO3 classes ------------------------------------------------
@@ -86,13 +87,15 @@ mod python {
     #[pymethods]
     impl PyDirSQL {
         #[new]
-        #[pyo3(signature = (root=None, *, tables=None, ignore=None, config=None))]
+        #[pyo3(signature = (root=None, *, tables=None, ignore=None, config=None, persist=false, persist_path=None))]
         fn new(
             py: Python<'_>,
             root: Option<String>,
             tables: Option<Vec<PyRef<'_, PyTable>>>,
             ignore: Option<Vec<String>>,
             config: Option<String>,
+            persist: bool,
+            persist_path: Option<PathBuf>,
         ) -> PyResult<Self> {
             let rust_tables: Vec<Table> = tables
                 .as_deref()
@@ -114,6 +117,12 @@ mod python {
                     if let Some(c) = config {
                         builder = builder.config(c);
                     }
+                    if persist {
+                        builder = builder.persist(true);
+                    }
+                    if let Some(p) = persist_path {
+                        builder = builder.persist_path(p);
+                    }
                     builder.build()
                 })
                 .map_err(to_py_err)?;

{dirsql-0.2.9 → dirsql-0.3.0}/packages/python/tests/integration/test_async_dirsql.py

@@ -282,6 +282,11 @@ def describe_DirSQL_async():
 
             async def collect_events():
                 async for event in db.watch():
+                    # Mid-write the watcher can deliver a spurious error
+                    # event before the real diff lands; only update / delete
+                    # / insert are meaningful here.
+                    if event.action not in ("update", "delete", "insert"):
+                        continue
                     events.append(event)
                     if len(events) >= 1:
                         break
@@ -322,6 +327,8 @@ def describe_DirSQL_async():
 
             async def collect_events():
                 async for event in db.watch():
+                    if event.action != "error":
+                        continue
                     events.append(event)
                     if len(events) >= 1:
                         break
@@ -369,6 +376,11 @@ def describe_DirSQL_async():
 
             async def collect_events():
                 async for event in db.watch():
+                    # Filter to insert events only: mid-write the watcher can
+                    # deliver a spurious error/update event before the insert
+                    # fires, which would race the query below.
+                    if event.action != "insert":
+                        continue
                     events.append(event)
                     if len(events) >= 1:
                         break

{dirsql-0.2.9 → dirsql-0.3.0}/packages/python/tests/integration/test_binding.py

@@ -27,11 +27,22 @@ class _FakeRustDirSQL:
 
     instances: list = []
 
-    def __init__(self, root=None, *, tables=None, ignore=None, config=None):
+    def __init__(
+        self,
+        root=None,
+        *,
+        tables=None,
+        ignore=None,
+        config=None,
+        persist=False,
+        persist_path=None,
+    ):
         self.root = root
         self.tables = tables
         self.ignore = ignore
         self.config = config
+        self.persist = persist
+        self.persist_path = persist_path
         self.queries: list[str] = []
         self.query_results: list = (
             [{"from_config": config}] if config is not None else [{"ok": 1}]
@@ -254,3 +265,26 @@ def describe_binding_layer():
             db = async_mod.DirSQL("/root", tables=["t"])
             await db.ready()
             assert _FakeRustDirSQL.instances[0].ignore is None
+
+    def describe_persist_kwargs():
+        # Feature: persist / persist_path. See docs/guide/persistence.md.
+        @pytest.mark.asyncio
+        async def it_forwards_persist_kwargs_to_core(mock_core):
+            db = async_mod.DirSQL(
+                "/root",
+                tables=["t"],
+                persist=True,
+                persist_path="/tmp/cache.db",
+            )
+            await db.ready()
+            inst = _FakeRustDirSQL.instances[0]
+            assert inst.persist is True
+            assert inst.persist_path == "/tmp/cache.db"
+
+        @pytest.mark.asyncio
+        async def it_defaults_persist_to_false(mock_core):
+            db = async_mod.DirSQL("/root", tables=["t"])
+            await db.ready()
+            inst = _FakeRustDirSQL.instances[0]
+            assert inst.persist is False
+            assert inst.persist_path is None