dirsql 0.3.21__tar.gz → 0.3.22__tar.gz

{dirsql-0.3.21 → dirsql-0.3.22}/Cargo.lock

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

{dirsql-0.3.21 → dirsql-0.3.22}/Cargo.toml

@@ -1,5 +1,9 @@
 [workspace]
 members = ["packages/python", "packages/rust"]
+# Test-only loadable-extension fixture, built on demand by
+# packages/rust/tests/extensions.rs. Excluded so it isn't built/linted by
+# `cargo build --workspace` / `cargo clippy --workspace`.
+exclude = ["packages/rust/tests/fixtures/testext"]
 resolver = "2"
 
 [workspace.package]

{dirsql-0.3.21 → dirsql-0.3.22}/PKG-INFO

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

{dirsql-0.3.21 → dirsql-0.3.22}/docs/cli/config.md

@@ -138,6 +138,33 @@ persist = true
 See [Persistence](../guide/persistence.md) for the full reconcile algorithm,
 storage layout, and limitations.
 
+## Loading extensions
+
+You can load SQLite extensions by specifying them in a config.
+
+Declare each extension as a `[[dirsql.extension]]` entry:
+
+```toml
+[[dirsql.extension]]
+path       = "./ext/myext.dylib"
+entrypoint = "sqlite3_myext_init"
+```
+
+- **`path`** — a path to the extension's shared library (`.so` / `.dylib` /
+  `.dll`). Relative paths resolve against the config file's parent directory.
+- **`entrypoint`** *(optional)* — the extension's init symbol. When omitted,
+  SQLite derives a default from the filename; set it when that default does not
+  match (for example, `sqlite-vec`'s entry point is `sqlite3_vec_init`).
+
+**Note**: `dirsql` enables extension loading only while loading the configured libraries,
+then disables it again, so `load_extension()` is not exposed via SQL to the user.
+
+Extensions add **functions** you can call in queries and in a regular table's
+DDL (defaults, generated columns). An extension-backed **virtual table** cannot
+be declared as a `[[table]]` — `dirsql` tables are per-file row tables — so a
+`CREATE VIRTUAL TABLE` DDL is rejected; call the extension's functions in your
+queries instead.
+
 ## Strict Mode
 
 By default, auto-injected virtuals that aren't in the DDL are silently

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

{dirsql-0.3.21/packages/rust → dirsql-0.3.22/packages/python}/docs/cli/config.md

@@ -138,6 +138,33 @@ persist = true
 See [Persistence](../guide/persistence.md) for the full reconcile algorithm,
 storage layout, and limitations.
 
+## Loading extensions
+
+You can load SQLite extensions by specifying them in a config.
+
+Declare each extension as a `[[dirsql.extension]]` entry:
+
+```toml
+[[dirsql.extension]]
+path       = "./ext/myext.dylib"
+entrypoint = "sqlite3_myext_init"
+```
+
+- **`path`** — a path to the extension's shared library (`.so` / `.dylib` /
+  `.dll`). Relative paths resolve against the config file's parent directory.
+- **`entrypoint`** *(optional)* — the extension's init symbol. When omitted,
+  SQLite derives a default from the filename; set it when that default does not
+  match (for example, `sqlite-vec`'s entry point is `sqlite3_vec_init`).
+
+**Note**: `dirsql` enables extension loading only while loading the configured libraries,
+then disables it again, so `load_extension()` is not exposed via SQL to the user.
+
+Extensions add **functions** you can call in queries and in a regular table's
+DDL (defaults, generated columns). An extension-backed **virtual table** cannot
+be declared as a `[[table]]` — `dirsql` tables are per-file row tables — so a
+`CREATE VIRTUAL TABLE` DDL is rejected; call the extension's functions in your
+queries instead.
+
 ## Strict Mode
 
 By default, auto-injected virtuals that aren't in the DDL are silently

{dirsql-0.3.21 → dirsql-0.3.22}/packages/rust/Cargo.toml

@@ -53,7 +53,7 @@ futures-channel.workspace = true
 globset = "0.4"
 notify = "7"
 regex.workspace = true
-rusqlite = { version = "0.34", features = ["bundled"] }
+rusqlite = { version = "0.34", features = ["bundled", "load_extension"] }
 serde.workspace = true
 serde_json.workspace = true
 thiserror.workspace = true

{dirsql-0.3.21/packages/python → dirsql-0.3.22/packages/rust}/docs/cli/config.md

@@ -138,6 +138,33 @@ persist = true
 See [Persistence](../guide/persistence.md) for the full reconcile algorithm,
 storage layout, and limitations.
 
+## Loading extensions
+
+You can load SQLite extensions by specifying them in a config.
+
+Declare each extension as a `[[dirsql.extension]]` entry:
+
+```toml
+[[dirsql.extension]]
+path       = "./ext/myext.dylib"
+entrypoint = "sqlite3_myext_init"
+```
+
+- **`path`** — a path to the extension's shared library (`.so` / `.dylib` /
+  `.dll`). Relative paths resolve against the config file's parent directory.
+- **`entrypoint`** *(optional)* — the extension's init symbol. When omitted,
+  SQLite derives a default from the filename; set it when that default does not
+  match (for example, `sqlite-vec`'s entry point is `sqlite3_vec_init`).
+
+**Note**: `dirsql` enables extension loading only while loading the configured libraries,
+then disables it again, so `load_extension()` is not exposed via SQL to the user.
+
+Extensions add **functions** you can call in queries and in a regular table's
+DDL (defaults, generated columns). An extension-backed **virtual table** cannot
+be declared as a `[[table]]` — `dirsql` tables are per-file row tables — so a
+`CREATE VIRTUAL TABLE` DDL is rejected; call the extension's functions in your
+queries instead.
+
 ## Strict Mode
 
 By default, auto-injected virtuals that aren't in the DDL are silently

{dirsql-0.3.21 → dirsql-0.3.22}/packages/rust/src/config.rs

@@ -13,6 +13,9 @@ pub enum ConfigError {
 
     #[error("Missing required field '{0}' in [[table]] entry")]
     MissingField(&'static str),
+
+    #[error("Missing required field '{0}' in [[dirsql.extension]] entry")]
+    MissingExtensionField(&'static str),
 }
 
 pub type Result<T> = std::result::Result<T, ConfigError>;
@@ -33,6 +36,29 @@ pub struct Config {
     /// Optional override for the on-disk cache location. Resolved relative
     /// to the config file's parent directory when relative.
     pub persist_path: Option<PathBuf>,
+    /// SQLite extensions to load at startup, declared via
+    /// `[[dirsql.extension]]`. Paths are taken verbatim from the file here;
+    /// relative paths are resolved against the config file's parent directory
+    /// by the caller (`DirSQLBuilder::resolve`).
+    pub extensions: Vec<ExtensionSpec>,
+}
+
+/// A SQLite extension to load at startup.
+///
+/// Declared as a `[[dirsql.extension]]` array entry. dirsql loads each
+/// extension onto the connection before any `CREATE TABLE` runs, then
+/// disables loading again so the SQL `load_extension()` function is never
+/// left exposed.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
+pub struct ExtensionSpec {
+    /// Local path to the extension's shared library (`.so` / `.dylib` /
+    /// `.dll`). Relative paths resolve against the config file's parent
+    /// directory.
+    pub path: PathBuf,
+    /// Optional init-symbol override. When `None`, SQLite derives the entry
+    /// point from the filename, which often does not match — set this when
+    /// the extension's init function isn't `sqlite3_<filename>_init`.
+    pub entrypoint: Option<String>,
 }
 
 /// Configuration for a single table.
@@ -65,6 +91,13 @@ struct RawDirsql {
     ignore: Option<Vec<String>>,
     persist: Option<bool>,
     persist_path: Option<PathBuf>,
+    extension: Option<Vec<RawExtension>>,
+}
+
+#[derive(Deserialize)]
+struct RawExtension {
+    path: Option<String>,
+    entrypoint: Option<String>,
 }
 
 #[derive(Deserialize)]
@@ -84,16 +117,31 @@ pub fn load_config(path: &Path) -> Result<Config> {
 pub fn load_config_str(content: &str) -> Result<Config> {
     let raw: RawConfig = toml::from_str(content)?;
 
-    let (root, ignore, persist, persist_path) = match raw.dirsql {
+    let (root, ignore, persist, persist_path, raw_extensions) = match raw.dirsql {
         Some(d) => (
             d.root,
             d.ignore.unwrap_or_default(),
             d.persist.unwrap_or(false),
             d.persist_path,
+            d.extension.unwrap_or_default(),
         ),
-        None => (None, Vec::new(), false, None),
+        None => (None, Vec::new(), false, None, Vec::new()),
     };
 
+    let mut extensions = Vec::with_capacity(raw_extensions.len());
+    for raw_ext in raw_extensions {
+        // An empty `path = ""` is as unusable as a missing key: reject it at
+        // parse time rather than silently resolving it to a directory later.
+        let path = raw_ext
+            .path
+            .filter(|p| !p.is_empty())
+            .ok_or(ConfigError::MissingExtensionField("path"))?;
+        extensions.push(ExtensionSpec {
+            path: PathBuf::from(path),
+            entrypoint: raw_ext.entrypoint,
+        });
+    }
+
     let raw_tables = raw.table.unwrap_or_default();
     let mut tables = Vec::with_capacity(raw_tables.len());
 
@@ -114,6 +162,7 @@ pub fn load_config_str(content: &str) -> Result<Config> {
         tables,
         persist,
         persist_path,
+        extensions,
     })
 }
 
@@ -341,4 +390,90 @@ format = "json"
         let config = load_config_str(toml).unwrap();
         assert_eq!(config.tables.len(), 1);
     }
+
+    #[test]
+    fn extensions_parse_path_and_entrypoint() {
+        let toml = r#"
+[[dirsql.extension]]
+path = "./ext/vec0.dylib"
+entrypoint = "sqlite3_vec_init"
+
+[[table]]
+ddl = "CREATE TABLE t (_path TEXT)"
+glob = "*.json"
+"#;
+        let config = load_config_str(toml).unwrap();
+        assert_eq!(config.extensions.len(), 1);
+        assert_eq!(config.extensions[0].path, PathBuf::from("./ext/vec0.dylib"));
+        assert_eq!(
+            config.extensions[0].entrypoint.as_deref(),
+            Some("sqlite3_vec_init")
+        );
+    }
+
+    #[test]
+    fn extension_entrypoint_is_optional() {
+        let toml = r#"
+[[dirsql.extension]]
+path = "ext.so"
+"#;
+        let config = load_config_str(toml).unwrap();
+        assert_eq!(config.extensions.len(), 1);
+        assert!(config.extensions[0].entrypoint.is_none());
+    }
+
+    #[test]
+    fn extension_missing_path_errors() {
+        let toml = r#"
+[[dirsql.extension]]
+entrypoint = "sqlite3_x_init"
+"#;
+        let err = load_config_str(toml).unwrap_err();
+        assert!(
+            matches!(err, ConfigError::MissingExtensionField("path")),
+            "got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn extensions_default_empty_when_absent() {
+        let toml = r#"
+[[table]]
+ddl = "CREATE TABLE t (_path TEXT)"
+glob = "*.json"
+"#;
+        let config = load_config_str(toml).unwrap();
+        assert!(config.extensions.is_empty());
+    }
+
+    #[test]
+    fn multiple_extensions_preserve_order() {
+        let toml = r#"
+[[dirsql.extension]]
+path = "a.so"
+
+[[dirsql.extension]]
+path = "b.so"
+"#;
+        let config = load_config_str(toml).unwrap();
+        assert_eq!(config.extensions.len(), 2);
+        assert_eq!(config.extensions[0].path, PathBuf::from("a.so"));
+        assert_eq!(config.extensions[1].path, PathBuf::from("b.so"));
+    }
+
+    #[test]
+    fn extension_empty_path_errors() {
+        // An empty `path = ""` is as unusable as a missing key — it must be
+        // rejected at parse time, not silently accepted and later resolved to
+        // the config's parent directory. (RED for #225 review finding #4.)
+        let toml = r#"
+[[dirsql.extension]]
+path = ""
+"#;
+        let err = load_config_str(toml).unwrap_err();
+        assert!(
+            matches!(err, ConfigError::MissingExtensionField("path")),
+            "got: {err:?}"
+        );
+    }
 }

{dirsql-0.3.21 → dirsql-0.3.22}/packages/rust/src/db.rs

@@ -75,6 +75,27 @@ impl Db {
         &self.conn
     }
 
+    /// Load a SQLite extension shared library onto this connection.
+    ///
+    /// `entrypoint` overrides the init symbol; when `None`, SQLite derives it
+    /// from the filename. Extension loading is enabled for the duration of the
+    /// call via [`rusqlite::LoadExtensionGuard`] and disabled again on return,
+    /// so the SQL `load_extension()` function is never left exposed to later
+    /// queries. A missing or unloadable file surfaces as [`DbError::Sqlite`].
+    pub fn load_extension(&self, path: &Path, entrypoint: Option<&str>) -> Result<()> {
+        // SAFETY: loading an extension executes native code from `path`. The
+        // path is operator-supplied configuration (a `[[dirsql.extension]]`
+        // entry), at the same trust level as the DDL the operator already
+        // controls. The guard enables loading on construction and disables it
+        // on drop at the end of this block — after the load — so the SQL
+        // `load_extension()` function is never left exposed to later queries.
+        unsafe {
+            let _guard = rusqlite::LoadExtensionGuard::new(&self.conn)?;
+            self.conn.load_extension(path, entrypoint)?;
+        }
+        Ok(())
+    }
+
     /// Create a table from a user-provided DDL statement.
     /// Automatically injects internal tracking columns (_dirsql_file_path, _dirsql_row_index).
     ///
@@ -83,6 +104,20 @@ impl Db {
     /// `CREATE TABLE foo;DROP_TABLE_bar--(id TEXT)` would parse to a poisoned
     /// internal table name and break downstream `format!()`-built SQL.
     pub fn create_table(&self, ddl: &str) -> Result<()> {
+        // A dirsql table is a per-file row table: create_table injects
+        // `_dirsql_` tracking columns and the engine inserts one row per file.
+        // That is structurally incompatible with an extension-backed virtual
+        // table, so reject `CREATE VIRTUAL TABLE` with a clear message instead
+        // of mangling the DDL via column injection. Load the extension and use
+        // its functions in queries instead.
+        if is_virtual_table_ddl(ddl) {
+            return Err(DbError::DdlParse(
+                "CREATE VIRTUAL TABLE is not supported as a dirsql table \
+                 (dirsql tables are per-file row tables); load the extension \
+                 and call its functions in queries instead"
+                    .to_string(),
+            ));
+        }
         let table = parse_table_name(ddl).ok_or_else(|| DbError::DdlParse(ddl.to_string()))?;
         validate_identifier(&table)?;
         let augmented = inject_tracking_columns(ddl)?;
@@ -390,6 +425,16 @@ pub fn parse_table_name(ddl: &str) -> Option<String> {
     if name.is_empty() { None } else { Some(name) }
 }
 
+/// True if `ddl` is a `CREATE VIRTUAL TABLE` statement. dirsql tables are
+/// per-file row tables (create_table injects `_dirsql_` tracking columns and
+/// inserts one row per file), which is structurally incompatible with an
+/// extension-backed virtual table — those are rejected with a clear error
+/// rather than mangled by column injection.
+fn is_virtual_table_ddl(ddl: &str) -> bool {
+    let normalized = ddl.split_whitespace().collect::<Vec<_>>().join(" ");
+    normalized.to_uppercase().contains("CREATE VIRTUAL TABLE")
+}
+
 impl From<rusqlite::types::Value> for Value {
     fn from(v: rusqlite::types::Value) -> Self {
         match v {
@@ -1078,4 +1123,55 @@ mod tests {
         assert_eq!(rows.len(), 1);
         assert!(!rows[0].contains_key("_dirsql_file_path"));
     }
+
+    // --- load_extension: error path (missing shared library) ---
+
+    #[test]
+    fn load_extension_missing_file_errors() {
+        // Loading is enabled for the call (the guard succeeds), the load of a
+        // nonexistent shared library fails, and the error propagates as
+        // DbError::Sqlite. Exercises the enable→load path; the success arm is
+        // covered by the integration suite against a real extension.
+        let db = Db::new().unwrap();
+        let err = db
+            .load_extension(Path::new("/nonexistent/dirsql-no-such-ext.so"), None)
+            .unwrap_err();
+        assert!(matches!(err, DbError::Sqlite(_)), "got: {err}");
+    }
+
+    // --- create_table: virtual tables are not supported as dirsql tables ---
+
+    #[test]
+    fn create_table_rejects_virtual_table_with_clear_error() {
+        // A dirsql table is a per-file row table: create_table injects
+        // _dirsql_ tracking columns and the engine inserts one row per file.
+        // That is structurally incompatible with an extension-backed virtual
+        // table, so a `CREATE VIRTUAL TABLE` DDL must fail with a clear,
+        // specific error rather than a confusing "no such module" / mangled
+        // DDL. (RED for #225 review finding #1.)
+        let db = Db::new().unwrap();
+        let err = db
+            .create_table("CREATE VIRTUAL TABLE vss USING vec0(embedding float[4])")
+            .unwrap_err();
+        // Must be a clear "not supported" message, NOT the generic
+        // `DdlParse` echo (which trivially contains "virtual table" because it
+        // echoes the DDL back).
+        let msg = err.to_string().to_lowercase();
+        assert!(
+            msg.contains("virtual table") && msg.contains("not supported"),
+            "expected a clear 'virtual table not supported' error, not a generic DDL-parse echo, got: {err}"
+        );
+    }
+
+    #[test]
+    fn is_virtual_table_ddl_detects_variants() {
+        assert!(is_virtual_table_ddl("CREATE VIRTUAL TABLE x USING vec0(a)"));
+        assert!(is_virtual_table_ddl(
+            "create   virtual   table x using fts5(a)"
+        ));
+        assert!(!is_virtual_table_ddl("CREATE TABLE x (a TEXT)"));
+        assert!(!is_virtual_table_ddl(
+            "CREATE TABLE IF NOT EXISTS x (a TEXT)"
+        ));
+    }
 }

{dirsql-0.3.21 → dirsql-0.3.22}/packages/rust/src/lib.rs

@@ -47,6 +47,7 @@ use std::thread;
 use std::time::Duration;
 use thiserror::Error;
 
+pub use crate::config::ExtensionSpec as Extension;
 pub use crate::db::{DbError, Value};
 pub use crate::differ::RowEvent;
 #[doc(hidden)]
@@ -89,6 +90,13 @@ pub enum DirSqlError {
     #[error("table DDL could not be parsed: {0}")]
     Ddl(String),
 
+    #[error("failed to load extension '{}': {source}", .path.display())]
+    Extension {
+        path: PathBuf,
+        #[source]
+        source: DbError,
+    },
+
     #[error("duplicate table name: {0}")]
     DuplicateTable(String),
 
@@ -232,6 +240,8 @@ struct DirSqlInner {
     table_configs: Vec<TableConfig>,
     /// Resolved ignore patterns preserved for [`DirSQL::config`].
     ignore: Vec<String>,
+    /// Configured SQLite extensions, preserved for [`DirSQL::config`].
+    extensions: Vec<Extension>,
     /// Whether persistent caching is enabled.
     persist: bool,
     /// Override location of the persistent cache file.
@@ -278,6 +288,8 @@ pub struct DirSQLConfig {
     pub ignore: Vec<String>,
     pub persist: bool,
     pub persist_path: Option<PathBuf>,
+    /// SQLite extensions loaded onto the connection at startup, in load order.
+    pub extensions: Vec<Extension>,
 }
 
 /// Serializable per-table portion of [`DirSQLConfig`]. Captures only the
@@ -357,6 +369,7 @@ impl DirSQL {
             ignore: self.inner.ignore.clone(),
             persist: self.inner.persist,
             persist_path: self.inner.persist_path.clone(),
+            extensions: self.inner.extensions.clone(),
         }
     }
 
@@ -641,6 +654,7 @@ impl DirSQL {
             root,
             tables,
             ignore,
+            extensions,
             persist,
             persist_path,
             poll_interval,
@@ -687,6 +701,7 @@ impl DirSQL {
         Ok(PreparedBuild {
             root,
             tables,
+            extensions,
             matcher,
             scanned_files,
             persist: persist_ctx.map(|ctx| PreparedPersist {
@@ -716,6 +731,7 @@ impl DirSQL {
         let PreparedBuild {
             root,
             tables,
+            extensions,
             matcher,
             scanned_files,
             persist,
@@ -730,6 +746,20 @@ impl DirSQL {
             None => (Db::new()?, None),
         };
 
+        // Load configured SQLite extensions onto the connection before any
+        // CREATE TABLE so a table's DDL and later queries can use
+        // extension-provided functions. (An extension-backed *virtual table*
+        // cannot be a dirsql-managed `[[table]]` — those inject per-file
+        // tracking columns; see Db::create_table.) Loading is enabled only for
+        // the duration of each load and disabled again afterwards.
+        for ext in &extensions {
+            db.load_extension(&ext.path, ext.entrypoint.as_deref())
+                .map_err(|source| DirSqlError::Extension {
+                    path: ext.path.clone(),
+                    source,
+                })?;
+        }
+
         let mut extract_map: HashMap<String, Arc<ExtractFn>> = HashMap::new();
         let mut strict_map: HashMap<String, bool> = HashMap::new();
         let mut ddl_map: HashMap<String, String> = HashMap::new();
@@ -849,6 +879,7 @@ impl DirSQL {
                 strict_map,
                 table_configs,
                 ignore,
+                extensions,
                 persist: persist_enabled,
                 persist_path,
                 file_rows: Mutex::new(file_rows),
@@ -892,6 +923,7 @@ pub struct DirSQLBuilder {
     root: Option<PathBuf>,
     tables: Vec<Table>,
     ignore: Vec<String>,
+    extensions: Vec<Extension>,
     config_path: Option<PathBuf>,
     persist: bool,
     persist_path: Option<PathBuf>,
@@ -929,6 +961,27 @@ impl DirSQLBuilder {
         self
     }
 
+    /// Append a single SQLite extension to load at startup. Extensions are
+    /// loaded onto the connection before any `CREATE TABLE`, then loading is
+    /// disabled again. See [`Extension`].
+    ///
+    /// A relative `path` here is used verbatim — the OS resolves it against the
+    /// process working directory at load time. Config-file paths, by contrast,
+    /// resolve against the config file's parent directory.
+    pub fn extension(mut self, extension: Extension) -> Self {
+        self.extensions.push(extension);
+        self
+    }
+
+    /// Replace the accumulated extension list with `extensions`.
+    pub fn extensions<I>(mut self, extensions: I) -> Self
+    where
+        I: IntoIterator<Item = Extension>,
+    {
+        self.extensions = extensions.into_iter().collect();
+        self
+    }
+
     /// Load a `.dirsql.toml` config file at build time. The file's `[[table]]`
     /// entries are appended after any programmatic tables; its `[dirsql].ignore`
     /// patterns are appended; its optional `[dirsql].root` is resolved relative
@@ -975,6 +1028,7 @@ impl DirSQLBuilder {
             root: explicit_root,
             mut tables,
             mut ignore,
+            mut extensions,
             config_path,
             mut persist,
             mut persist_path,
@@ -1005,6 +1059,21 @@ impl DirSQLBuilder {
             tables.extend(cfg_tables);
             ignore.extend(cfg.ignore);
 
+            // Resolve config-supplied extension paths against the config
+            // file's parent directory (absolute paths pass through). Appended
+            // after any programmatically-supplied extensions.
+            for ext in cfg.extensions {
+                let path = if ext.path.is_absolute() {
+                    ext.path
+                } else {
+                    cfg_parent.join(&ext.path)
+                };
+                extensions.push(Extension {
+                    path,
+                    entrypoint: ext.entrypoint,
+                });
+            }
+
             if cfg.persist {
                 persist = true;
             }
@@ -1045,6 +1114,7 @@ impl DirSQLBuilder {
             root,
             tables,
             ignore,
+            extensions,
             persist,
             persist_path,
             poll_interval: poll_interval.unwrap_or(DEFAULT_POLL_INTERVAL),
@@ -1087,6 +1157,7 @@ pub struct ResolvedBuild {
     pub root: PathBuf,
     pub tables: Vec<Table>,
     pub ignore: Vec<String>,
+    pub extensions: Vec<Extension>,
     pub persist: bool,
     pub persist_path: Option<PathBuf>,
     pub poll_interval: Duration,
@@ -1109,6 +1180,8 @@ pub struct ScannedFile {
 pub struct PreparedBuild {
     root: PathBuf,
     tables: Vec<Table>,
+    /// SQLite extensions to load onto the connection before any table DDL.
+    extensions: Vec<Extension>,
     matcher: TableMatcher,
     scanned_files: Vec<ScannedFile>,
     persist: Option<PreparedPersist>,
@@ -1616,6 +1689,28 @@ mod readonly_tests {
         assert!(matches!(err, DirSqlError::Core(_)), "got: {err:?}");
     }
 
+    #[test]
+    fn missing_extension_build_fails_with_extension_error() {
+        // The .extension() builder surface loads at startup; a missing file
+        // must surface as DirSqlError::Extension (naming the library), not the
+        // generic Core(Sqlite) error. (#225 review finding #9; also exercises
+        // the .extension() builder method in-process.)
+        let dir = tempfile::tempdir().unwrap();
+        let err = match DirSQL::builder()
+            .root(dir.path())
+            .extension(Extension {
+                path: "/nonexistent/dirsql-no-such.so".into(),
+                entrypoint: None,
+            })
+            .build()
+        {
+            Ok(_) => panic!("expected build to fail on a missing extension"),
+            Err(e) => e,
+        };
+        assert!(matches!(err, DirSqlError::Extension { .. }), "got: {err:?}");
+        assert!(err.to_string().contains("failed to load extension"));
+    }
+
     #[test]
     fn error_helpers_build_expected_variants() {
         // Exercise the `map_err` helper constructors directly; their runtime
@@ -1716,6 +1811,7 @@ mod internal_tests {
         let prepared = PreparedBuild {
             root: dir.path().to_path_buf(),
             tables: Vec::new(),
+            extensions: Vec::new(),
             matcher,
             scanned_files: vec![ScannedFile {
                 rel_path: "ghost.txt".into(),