dirsql 0.3.31__tar.gz → 0.3.33__tar.gz

{dirsql-0.3.31 → dirsql-0.3.33}/Cargo.lock

@@ -499,7 +499,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.3.31"
+version = "0.3.33"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.3.31 → dirsql-0.3.33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.3.31
+Version: 0.3.33
 Requires-Dist: pytest>=8 ; extra == 'dev'
 Requires-Dist: pytest-describe>=2 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'
@@ -98,6 +98,27 @@ db = DirSQL(
 )
 ```
 
+## Loading SQLite extensions
+
+Pass `extensions` to load SQLite extension shared libraries onto the connection at startup (before any `CREATE TABLE`). Each entry is a dict with a `path` and an optional `entrypoint` init-symbol override:
+
+```python
+db = DirSQL(
+    "./my-blog",
+    tables=[...],
+    extensions=[
+        {"path": "./ext/vec0.dylib", "entrypoint": "sqlite3_vec_init"},
+        {"path": "./ext/myext.so"},  # entrypoint derived from the filename
+    ],
+)
+await db.ready()
+
+# The extension's functions are now callable in queries:
+rows = await db.query("SELECT vec_version() AS v")
+```
+
+`dirsql` enables extension loading only while loading the configured libraries, then disables it again, so the SQL `load_extension()` function is never exposed to your queries. Programmatic entries load first, followed by any `[[dirsql.extension]]` entries declared in a `config` file. See the [config reference](https://github.com/thekevinscott/dirsql/blob/main/docs/cli/config.md#loading-extensions).
+
 ## Watching for changes
 
 `db.watch()` returns an async iterator of row-level change events as files change on disk:

{dirsql-0.3.31/packages/python → dirsql-0.3.33}/README.md

@@ -80,6 +80,27 @@ db = DirSQL(
 )
 ```
 
+## Loading SQLite extensions
+
+Pass `extensions` to load SQLite extension shared libraries onto the connection at startup (before any `CREATE TABLE`). Each entry is a dict with a `path` and an optional `entrypoint` init-symbol override:
+
+```python
+db = DirSQL(
+    "./my-blog",
+    tables=[...],
+    extensions=[
+        {"path": "./ext/vec0.dylib", "entrypoint": "sqlite3_vec_init"},
+        {"path": "./ext/myext.so"},  # entrypoint derived from the filename
+    ],
+)
+await db.ready()
+
+# The extension's functions are now callable in queries:
+rows = await db.query("SELECT vec_version() AS v")
+```
+
+`dirsql` enables extension loading only while loading the configured libraries, then disables it again, so the SQL `load_extension()` function is never exposed to your queries. Programmatic entries load first, followed by any `[[dirsql.extension]]` entries declared in a `config` file. See the [config reference](https://github.com/thekevinscott/dirsql/blob/main/docs/cli/config.md#loading-extensions).
+
 ## Watching for changes
 
 `db.watch()` returns an async iterator of row-level change events as files change on disk:

{dirsql-0.3.31 → dirsql-0.3.33}/dirsql/_async.py

@@ -50,6 +50,11 @@ class DirSQL:
 
     Pass ``persist=True`` to keep an on-disk SQLite cache (default location:
     ``<root>/.dirsql/cache.db``). Override the location with ``persist_path``.
+
+    Pass ``extensions`` -- a list of ``{"path": ..., "entrypoint": ...}`` dicts
+    (``entrypoint`` optional) -- to load SQLite extensions onto the connection
+    at startup. Any ``[[dirsql.extension]]`` entries in a ``config`` file are
+    appended after the programmatic ones.
     """
 
     def __init__(
@@ -61,6 +66,7 @@ class DirSQL:
         config=None,
         persist=False,
         persist_path=None,
+        extensions=None,
     ):
         if root is None and config is None:
             raise TypeError("DirSQL requires either a root directory or a config= path")
@@ -70,6 +76,7 @@ class DirSQL:
         self._config = config
         self._persist = persist
         self._persist_path = persist_path
+        self._extensions = extensions
         self._db = None
         self._ready_event = asyncio.Event()
         self._init_error = None
@@ -86,6 +93,7 @@ class DirSQL:
                 config=self._config,
                 persist=self._persist,
                 persist_path=self._persist_path,
+                extensions=self._extensions,
             )
         except Exception as exc:
             self._init_error = exc
@@ -124,4 +132,5 @@ class DirSQL:
             self._config,
             self._persist,
             self._persist_path,
+            self._extensions,
         )

{dirsql-0.3.31 → dirsql-0.3.33}/dirsql/_dirsql.pyi

@@ -11,12 +11,20 @@ same PR -- and ``PARITY.md`` is the canonical reminder.
 
 from collections.abc import Callable
 from os import PathLike
-from typing import Any
+from typing import Any, NotRequired, TypedDict
 
 __version__: str
 
 Row = dict[str, Any]
 
+class ExtensionSpec(TypedDict):
+    """A SQLite extension to load at startup: a shared-library ``path`` and an
+    optional ``entrypoint`` init-symbol override. Mirrors a
+    ``[[dirsql.extension]]`` config entry."""
+
+    path: str
+    entrypoint: NotRequired[str]
+
 class Table:
     """A table definition. Construct via keyword arguments only."""
 
@@ -57,6 +65,7 @@ class DirSQL:
         config: str | None = None,
         persist: bool = False,
         persist_path: str | PathLike[str] | None = None,
+        extensions: list[ExtensionSpec] | None = None,
     ) -> None: ...
     def query(self, sql: str) -> list[Row]: ...
     def _start_watcher(self) -> None: ...

{dirsql-0.3.31 → dirsql-0.3.33}/dirsql/resolve_config.py

@@ -9,14 +9,17 @@ import os
 import tomllib
 
 
-def resolve_config(root, tables, ignore, config, persist, persist_path):
+def resolve_config(
+    root, tables, ignore, config, persist, persist_path, extensions=None
+):
     """Merge kwargs with a `.dirsql.toml` into the serialized state shape."""
-    cfg, cfg_tables, cfg_dir = {}, [], None
+    cfg, cfg_tables, cfg_extensions, cfg_dir = {}, [], [], None
     if config is not None:
         with open(config, "rb") as f:
             doc = tomllib.load(f)
         cfg = doc.get("dirsql") or {}
         cfg_tables = doc.get("table") or []
+        cfg_extensions = cfg.get("extension") or []
         cfg_dir = os.path.dirname(os.path.abspath(config))
 
     def _abs(p):
@@ -40,4 +43,15 @@ def resolve_config(root, tables, ignore, config, persist, persist_path):
         "persist": bool(persist or cfg.get("persist")),
         "persist_path": persist_path
         or (_abs(cfg["persist_path"]) if "persist_path" in cfg else None),
+        # Programmatic extensions first (verbatim paths, mirroring the Rust
+        # builder), then config-file `[[dirsql.extension]]` entries with
+        # relative paths resolved against the config's parent directory.
+        "extensions": [
+            {"path": e["path"], "entrypoint": e.get("entrypoint")}
+            for e in (extensions or [])
+        ]
+        + [
+            {"path": _abs(e["path"]), "entrypoint": e.get("entrypoint")}
+            for e in cfg_extensions
+        ],
     }

{dirsql-0.3.31 → dirsql-0.3.33}/docs/api/index.md

@@ -37,6 +37,7 @@ DirSQL(
     tables: list[Table] | None = None,
     ignore: list[str] | None = None,
     config: str | None = None,
+    extensions: list[dict] | None = None,  # [{ "path": str, "entrypoint"?: str }]
 )
 ```
 
@@ -46,6 +47,7 @@ DirSQL::builder()
     .tables(tables)             // optional; append with .table(t)
     .ignore(patterns)           // optional
     .config(config_toml_path)   // optional
+    .extensions(extensions)     // optional; Extension { path, entrypoint }
     .build()                    // -> Result<DirSQL>
 ```
 
@@ -73,7 +75,8 @@ In Python, the constructor starts scanning in a background thread and returns im
 - `root` -- Path to the directory to index. Optional if `config` is supplied.
 - `tables` -- List of `Table` definitions. Each defines a SQLite table, a glob pattern, and an extract function.
 - `ignore` -- Optional list of glob patterns. Files matching any ignore pattern are skipped regardless of table globs.
-- `config` -- Optional path to a `.dirsql.toml` config file. Its `[[table]]` entries are appended to any programmatic `tables`; its `[dirsql].ignore` patterns are appended to any explicit `ignore`; its optional `[dirsql].root` supplies the root directory when `root` is not passed explicitly.
+- `config` -- Optional path to a `.dirsql.toml` config file. Its `[[table]]` entries are appended to any programmatic `tables`; its `[dirsql].ignore` patterns are appended to any explicit `ignore`; its optional `[dirsql].root` supplies the root directory when `root` is not passed explicitly; its `[[dirsql.extension]]` entries are appended to any programmatic `extensions`.
+- `extensions` -- Optional SQLite extensions to load onto the connection at startup, before any table DDL (enable → load → disable, so the SQL `load_extension()` function is never left exposed). Each entry pairs a shared-library `path` with an optional `entrypoint` init-symbol override (Python: `{ "path", "entrypoint"? }` dicts; Rust: `Extension { path, entrypoint }`). Programmatic entries load first, then any `[[dirsql.extension]]` from `config`. Available in the Python and Rust SDKs; the TypeScript constructor parameter is tracked in [#230](https://github.com/thekevinscott/dirsql/issues/230). See [Loading extensions](../cli/config.md#loading-extensions).
 
 ### Methods
 
@@ -159,7 +162,7 @@ JSON.stringify(db)  // via db.toJSON()
 
 :::
 
-Returns the resolved construction state as a JSON-compatible value with fields `root`, `tables`, `ignore`, `persist`, `persist_path` (camelCase `persistPath` in TypeScript). Each table is `{ ddl, glob, strict }`. Excludes the original `config` path (already merged into `root` / `tables` / `ignore`), per-table `extract`, and per-table `name`. Available immediately after construction in Python and TypeScript; Rust's sync `build()` returns a ready instance.
+Returns the resolved construction state as a JSON-compatible value with fields `root`, `tables`, `ignore`, `persist`, `persist_path` (camelCase `persistPath` in TypeScript). Each table is `{ ddl, glob, strict }`. The Python and Rust snapshots also include `extensions` -- an array of `{ path, entrypoint }` (empty when none are configured); the TypeScript `toJSON` snapshot will gain it with [#230](https://github.com/thekevinscott/dirsql/issues/230). Excludes the original `config` path (already merged into `root` / `tables` / `ignore`), per-table `extract`, and per-table `name`. Available immediately after construction in Python and TypeScript; Rust's sync `build()` returns a ready instance.
 
 ---
 

{dirsql-0.3.31 → dirsql-0.3.33}/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.3.31"
+version = "0.3.33"
 edition.workspace = true
 publish = false
 readme = "README.md"

{dirsql-0.3.31 → dirsql-0.3.33/packages/python}/README.md

@@ -80,6 +80,27 @@ db = DirSQL(
 )
 ```
 
+## Loading SQLite extensions
+
+Pass `extensions` to load SQLite extension shared libraries onto the connection at startup (before any `CREATE TABLE`). Each entry is a dict with a `path` and an optional `entrypoint` init-symbol override:
+
+```python
+db = DirSQL(
+    "./my-blog",
+    tables=[...],
+    extensions=[
+        {"path": "./ext/vec0.dylib", "entrypoint": "sqlite3_vec_init"},
+        {"path": "./ext/myext.so"},  # entrypoint derived from the filename
+    ],
+)
+await db.ready()
+
+# The extension's functions are now callable in queries:
+rows = await db.query("SELECT vec_version() AS v")
+```
+
+`dirsql` enables extension loading only while loading the configured libraries, then disables it again, so the SQL `load_extension()` function is never exposed to your queries. Programmatic entries load first, followed by any `[[dirsql.extension]]` entries declared in a `config` file. See the [config reference](https://github.com/thekevinscott/dirsql/blob/main/docs/cli/config.md#loading-extensions).
+
 ## Watching for changes
 
 `db.watch()` returns an async iterator of row-level change events as files change on disk:

{dirsql-0.3.31/packages/rust → dirsql-0.3.33/packages/python}/docs/api/index.md

@@ -37,6 +37,7 @@ DirSQL(
     tables: list[Table] | None = None,
     ignore: list[str] | None = None,
     config: str | None = None,
+    extensions: list[dict] | None = None,  # [{ "path": str, "entrypoint"?: str }]
 )
 ```
 
@@ -46,6 +47,7 @@ DirSQL::builder()
     .tables(tables)             // optional; append with .table(t)
     .ignore(patterns)           // optional
     .config(config_toml_path)   // optional
+    .extensions(extensions)     // optional; Extension { path, entrypoint }
     .build()                    // -> Result<DirSQL>
 ```
 
@@ -73,7 +75,8 @@ In Python, the constructor starts scanning in a background thread and returns im
 - `root` -- Path to the directory to index. Optional if `config` is supplied.
 - `tables` -- List of `Table` definitions. Each defines a SQLite table, a glob pattern, and an extract function.
 - `ignore` -- Optional list of glob patterns. Files matching any ignore pattern are skipped regardless of table globs.
-- `config` -- Optional path to a `.dirsql.toml` config file. Its `[[table]]` entries are appended to any programmatic `tables`; its `[dirsql].ignore` patterns are appended to any explicit `ignore`; its optional `[dirsql].root` supplies the root directory when `root` is not passed explicitly.
+- `config` -- Optional path to a `.dirsql.toml` config file. Its `[[table]]` entries are appended to any programmatic `tables`; its `[dirsql].ignore` patterns are appended to any explicit `ignore`; its optional `[dirsql].root` supplies the root directory when `root` is not passed explicitly; its `[[dirsql.extension]]` entries are appended to any programmatic `extensions`.
+- `extensions` -- Optional SQLite extensions to load onto the connection at startup, before any table DDL (enable → load → disable, so the SQL `load_extension()` function is never left exposed). Each entry pairs a shared-library `path` with an optional `entrypoint` init-symbol override (Python: `{ "path", "entrypoint"? }` dicts; Rust: `Extension { path, entrypoint }`). Programmatic entries load first, then any `[[dirsql.extension]]` from `config`. Available in the Python and Rust SDKs; the TypeScript constructor parameter is tracked in [#230](https://github.com/thekevinscott/dirsql/issues/230). See [Loading extensions](../cli/config.md#loading-extensions).
 
 ### Methods
 
@@ -159,7 +162,7 @@ JSON.stringify(db)  // via db.toJSON()
 
 :::
 
-Returns the resolved construction state as a JSON-compatible value with fields `root`, `tables`, `ignore`, `persist`, `persist_path` (camelCase `persistPath` in TypeScript). Each table is `{ ddl, glob, strict }`. Excludes the original `config` path (already merged into `root` / `tables` / `ignore`), per-table `extract`, and per-table `name`. Available immediately after construction in Python and TypeScript; Rust's sync `build()` returns a ready instance.
+Returns the resolved construction state as a JSON-compatible value with fields `root`, `tables`, `ignore`, `persist`, `persist_path` (camelCase `persistPath` in TypeScript). Each table is `{ ddl, glob, strict }`. The Python and Rust snapshots also include `extensions` -- an array of `{ path, entrypoint }` (empty when none are configured); the TypeScript `toJSON` snapshot will gain it with [#230](https://github.com/thekevinscott/dirsql/issues/230). Excludes the original `config` path (already merged into `root` / `tables` / `ignore`), per-table `extract`, and per-table `name`. Available immediately after construction in Python and TypeScript; Rust's sync `build()` returns a ready instance.
 
 ---
 

{dirsql-0.3.31 → dirsql-0.3.33}/packages/python/src/lib.rs

@@ -12,7 +12,7 @@
 
 #[cfg(feature = "extension-module")]
 mod python {
-    use ::dirsql::{DirSQL, Row, RowEvent, Table, Value, db::parse_table_name};
+    use ::dirsql::{DirSQL, Extension, Row, RowEvent, Table, Value, db::parse_table_name};
     use pyo3::exceptions::PyRuntimeError;
     use pyo3::prelude::*;
     use pyo3::types::{PyDict, PyList};
@@ -63,6 +63,20 @@ mod python {
         }
     }
 
+    /// Marshals a Python `{"path": str, "entrypoint"?: str}` mapping from the
+    /// `extensions=` constructor argument into a [`dirsql::Extension`]. Mirrors
+    /// the `[[dirsql.extension]]` config-file fields and the Rust builder's
+    /// `Extension { path, entrypoint }`. Paths are taken verbatim (the
+    /// programmatic surface does not resolve relative paths), matching
+    /// `DirSQLBuilder::extensions`.
+    #[derive(FromPyObject)]
+    struct PyExtensionSpec {
+        #[pyo3(item)]
+        path: String,
+        #[pyo3(item, default)]
+        entrypoint: Option<String>,
+    }
+
     /// A row event produced by the watch loop.
     ///
     /// `table` is `Optional[str]` because error events may occur before a
@@ -101,7 +115,7 @@ mod python {
     #[pymethods]
     impl PyDirSQL {
         #[new]
-        #[pyo3(signature = (root=None, *, tables=None, ignore=None, config=None, persist=false, persist_path=None))]
+        #[pyo3(signature = (root=None, *, tables=None, ignore=None, config=None, persist=false, persist_path=None, extensions=None))]
         fn new(
             py: Python<'_>,
             root: Option<String>,
@@ -110,12 +124,22 @@ mod python {
             config: Option<String>,
             persist: bool,
             persist_path: Option<PathBuf>,
+            extensions: Option<Vec<PyExtensionSpec>>,
         ) -> PyResult<Self> {
             let rust_tables: Vec<Table> = tables
                 .as_deref()
                 .map(|ts| ts.iter().map(|t| build_table(py, t)).collect())
                 .unwrap_or_default();
 
+            let rust_extensions: Vec<Extension> = extensions
+                .unwrap_or_default()
+                .into_iter()
+                .map(|e| Extension {
+                    path: PathBuf::from(e.path),
+                    entrypoint: e.entrypoint,
+                })
+                .collect();
+
             let inner = py
                 .detach(move || {
                     let mut builder = DirSQL::builder();
@@ -137,6 +161,9 @@ mod python {
                     if let Some(p) = persist_path {
                         builder = builder.persist_path(p);
                     }
+                    if !rust_extensions.is_empty() {
+                        builder = builder.extensions(rust_extensions);
+                    }
                     builder.build()
                 })
                 .map_err(to_py_err)?;

{dirsql-0.3.31 → dirsql-0.3.33}/packages/rust/Cargo.toml

@@ -16,7 +16,11 @@ license = "MIT"
 repository.workspace = true
 # `docs/` is a symlink to the workspace `docs/` so the markdown ships with the
 # crate; everything below is the VitePress build tooling we don't want to ship.
+# `tests/` is the integration suite -- excluded so test files never ship in the
+# published `.crate` (enforced by the `packaging` gate in CI). Inline unit tests
+# stay (they are `#[cfg(test)]` modules inside `src/`, not separate files).
 exclude = [
+    "tests/",
     "docs/.vitepress",
     "docs/.claude",
     "docs/tests",

{dirsql-0.3.31/packages/python → dirsql-0.3.33/packages/rust}/docs/api/index.md

@@ -37,6 +37,7 @@ DirSQL(
     tables: list[Table] | None = None,
     ignore: list[str] | None = None,
     config: str | None = None,
+    extensions: list[dict] | None = None,  # [{ "path": str, "entrypoint"?: str }]
 )
 ```
 
@@ -46,6 +47,7 @@ DirSQL::builder()
     .tables(tables)             // optional; append with .table(t)
     .ignore(patterns)           // optional
     .config(config_toml_path)   // optional
+    .extensions(extensions)     // optional; Extension { path, entrypoint }
     .build()                    // -> Result<DirSQL>
 ```
 
@@ -73,7 +75,8 @@ In Python, the constructor starts scanning in a background thread and returns im
 - `root` -- Path to the directory to index. Optional if `config` is supplied.
 - `tables` -- List of `Table` definitions. Each defines a SQLite table, a glob pattern, and an extract function.
 - `ignore` -- Optional list of glob patterns. Files matching any ignore pattern are skipped regardless of table globs.
-- `config` -- Optional path to a `.dirsql.toml` config file. Its `[[table]]` entries are appended to any programmatic `tables`; its `[dirsql].ignore` patterns are appended to any explicit `ignore`; its optional `[dirsql].root` supplies the root directory when `root` is not passed explicitly.
+- `config` -- Optional path to a `.dirsql.toml` config file. Its `[[table]]` entries are appended to any programmatic `tables`; its `[dirsql].ignore` patterns are appended to any explicit `ignore`; its optional `[dirsql].root` supplies the root directory when `root` is not passed explicitly; its `[[dirsql.extension]]` entries are appended to any programmatic `extensions`.
+- `extensions` -- Optional SQLite extensions to load onto the connection at startup, before any table DDL (enable → load → disable, so the SQL `load_extension()` function is never left exposed). Each entry pairs a shared-library `path` with an optional `entrypoint` init-symbol override (Python: `{ "path", "entrypoint"? }` dicts; Rust: `Extension { path, entrypoint }`). Programmatic entries load first, then any `[[dirsql.extension]]` from `config`. Available in the Python and Rust SDKs; the TypeScript constructor parameter is tracked in [#230](https://github.com/thekevinscott/dirsql/issues/230). See [Loading extensions](../cli/config.md#loading-extensions).
 
 ### Methods
 
@@ -159,7 +162,7 @@ JSON.stringify(db)  // via db.toJSON()
 
 :::
 
-Returns the resolved construction state as a JSON-compatible value with fields `root`, `tables`, `ignore`, `persist`, `persist_path` (camelCase `persistPath` in TypeScript). Each table is `{ ddl, glob, strict }`. Excludes the original `config` path (already merged into `root` / `tables` / `ignore`), per-table `extract`, and per-table `name`. Available immediately after construction in Python and TypeScript; Rust's sync `build()` returns a ready instance.
+Returns the resolved construction state as a JSON-compatible value with fields `root`, `tables`, `ignore`, `persist`, `persist_path` (camelCase `persistPath` in TypeScript). Each table is `{ ddl, glob, strict }`. The Python and Rust snapshots also include `extensions` -- an array of `{ path, entrypoint }` (empty when none are configured); the TypeScript `toJSON` snapshot will gain it with [#230](https://github.com/thekevinscott/dirsql/issues/230). Excludes the original `config` path (already merged into `root` / `tables` / `ignore`), per-table `extract`, and per-table `name`. Available immediately after construction in Python and TypeScript; Rust's sync `build()` returns a ready instance.
 
 ---
 

{dirsql-0.3.31 → dirsql-0.3.33}/packages/rust/src/cli/native_config.rs

@@ -21,7 +21,7 @@ use std::sync::{Arc, Mutex};
 use serde::Deserialize;
 
 use crate::db::parse_table_name;
-use crate::{DirSQL, Row, Table, Value};
+use crate::{DirSQL, Extension, Row, Table, Value};
 
 /// NDJSON helper subprocess + the shared IO it dispatches over.
 pub struct InterpretHelper {
@@ -57,6 +57,12 @@ struct HandshakeState {
     persist: bool,
     #[serde(default, alias = "persistPath")]
     persist_path: Option<String>,
+    /// SQLite extensions the config declared (`{path, entrypoint?}` each).
+    /// Defaults to empty so a handshake from an SDK that doesn't yet emit
+    /// the key still parses. Paths are taken verbatim — the SDK already
+    /// resolved config-relative paths before serializing the snapshot.
+    #[serde(default)]
+    extensions: Vec<HandshakeExtension>,
 }
 
 #[derive(Debug, Deserialize)]
@@ -67,6 +73,13 @@ struct HandshakeTable {
     strict: bool,
 }
 
+#[derive(Debug, Deserialize)]
+struct HandshakeExtension {
+    path: String,
+    #[serde(default)]
+    entrypoint: Option<String>,
+}
+
 /// Response per extract request. The discriminator `type` field and the
 /// echoed `id` field are ignored — V1 of the protocol is strictly
 /// sequential, so the helper's reply is unambiguous.
@@ -149,6 +162,14 @@ fn parse_handshake(stdout: &mut dyn BufRead) -> Result<NativeConfig, String> {
         ignore: state.ignore,
         persist: state.persist,
         persist_path: state.persist_path.map(PathBuf::from),
+        extensions: state
+            .extensions
+            .into_iter()
+            .map(|e| Extension {
+                path: PathBuf::from(e.path),
+                entrypoint: e.entrypoint,
+            })
+            .collect(),
     })
 }
 
@@ -203,6 +224,10 @@ pub struct NativeConfig {
     pub ignore: Vec<String>,
     pub persist: bool,
     pub persist_path: Option<PathBuf>,
+    /// SQLite extensions to load onto the connection at startup. Resolved
+    /// verbatim from the handshake (the SDK already merged config-file and
+    /// programmatic entries and resolved relative paths). See [`Extension`].
+    pub extensions: Vec<Extension>,
 }
 
 /// Build a [`DirSQL`] from a spawned interpret helper. Each table's
@@ -229,7 +254,8 @@ pub fn build_dirsql(helper: Arc<InterpretHelper>, config: NativeConfig) -> Resul
     let mut builder = DirSQL::builder()
         .root(config.root)
         .tables(tables)
-        .ignore(config.ignore);
+        .ignore(config.ignore)
+        .extensions(config.extensions);
     if config.persist {
         builder = builder.persist(true);
     }
@@ -317,6 +343,39 @@ mod tests {
         assert_eq!(cfg.ignore, vec!["a".to_string(), "b".to_string()]);
     }
 
+    #[test]
+    fn parse_handshake_carries_extensions_with_path_and_entrypoint() {
+        // A `.py` / `.js` config that declares `extensions=[...]` serializes
+        // them into the handshake `state`; the parser must carry both `path`
+        // and the optional `entrypoint` through to the resolved config (#229).
+        let line = br#"{"type":"config","state":{"root":"/r","tables":[],"extensions":[{"path":"/ext/vec0.so","entrypoint":"sqlite3_vec_init"}]}}
+"#;
+        let cfg = parse_handshake(&mut Cursor::new(line.as_slice())).unwrap();
+        assert_eq!(cfg.extensions.len(), 1);
+        assert_eq!(cfg.extensions[0].path, PathBuf::from("/ext/vec0.so"));
+        assert_eq!(
+            cfg.extensions[0].entrypoint.as_deref(),
+            Some("sqlite3_vec_init"),
+        );
+    }
+
+    #[test]
+    fn parse_handshake_extension_entrypoint_is_optional() {
+        let line = br#"{"type":"config","state":{"root":"/r","tables":[],"extensions":[{"path":"/ext/a.so"}]}}
+"#;
+        let cfg = parse_handshake(&mut Cursor::new(line.as_slice())).unwrap();
+        assert_eq!(cfg.extensions.len(), 1);
+        assert!(cfg.extensions[0].entrypoint.is_none());
+    }
+
+    #[test]
+    fn parse_handshake_defaults_extensions_to_empty_when_absent() {
+        let line = br#"{"type":"config","state":{"root":"/r","tables":[]}}
+"#;
+        let cfg = parse_handshake(&mut Cursor::new(line.as_slice())).unwrap();
+        assert!(cfg.extensions.is_empty());
+    }
+
     #[test]
     fn parse_handshake_errors_on_empty_stream() {
         let mut reader = Cursor::new(b"".as_slice());
@@ -505,6 +564,35 @@ mod tests {
         assert!(cache_path.exists(), "persist build should create the cache");
     }
 
+    #[test]
+    fn build_dirsql_threads_extensions_into_the_builder() {
+        // A handshake whose `extensions` names a missing shared library must
+        // fail the build, proving the parsed extensions reach the core's
+        // load-at-startup path (enable -> load -> disable). (#229)
+        let tmp = tempfile::TempDir::new().unwrap();
+        std::fs::write(tmp.path().join("a.json"), b"{}").unwrap();
+
+        let handshake = format!(
+            r#"{{"type":"config","state":{{"root":"{}","tables":[{{"ddl":"CREATE TABLE papers (title TEXT)","glob":"*.json"}}],"extensions":[{{"path":"/nonexistent/dirsql-no-such-ext.so"}}]}}}}"#,
+            tmp.path().display(),
+        );
+        let (helper, config) = spawn_fake_helper(
+            &handshake,
+            r#"{"type":"result","id":1,"ok":true,"rows":[{"title":"y"}]}"#,
+        );
+        assert_eq!(config.extensions.len(), 1);
+        assert_eq!(
+            config.extensions[0].path,
+            PathBuf::from("/nonexistent/dirsql-no-such-ext.so"),
+        );
+
+        let err = match build_dirsql(helper, config) {
+            Ok(_) => panic!("expected build to fail on a missing extension"),
+            Err(e) => e,
+        };
+        assert!(err.contains("failed to load extension"), "got: {err}");
+    }
+
     #[test]
     fn build_dirsql_round_trip_with_fake_helper_invokes_extract_per_matched_file() {
         // Create a tempdir with two matching files so the scan invokes
@@ -683,6 +771,7 @@ mod tests {
             ignore: Vec::new(),
             persist: false,
             persist_path: None,
+            extensions: Vec::new(),
         };
         // `DirSQL` doesn't impl Debug, so we can't use `unwrap_err` directly.
         let err = match build_dirsql(helper, config) {