Skip to main content

paper/core/index/
connection.rs

1use anyhow::{Context, Result};
2use rusqlite::OptionalExtension;
3use std::path::Path;
4use std::sync::Once;
5
6static REGISTER_VEC: Once = Once::new();
7
8/// Register `sqlite-vec` as a SQLite auto-extension exactly once per process.
9///
10/// The C extension is compiled statically into the binary (no runtime `.dylib`
11/// download, no `load_extension` call), which keeps `paper` a single binary.
12#[allow(clippy::missing_transmute_annotations)]
13pub fn register_sqlite_vec() {
14    REGISTER_VEC.call_once(|| unsafe {
15        // SAFETY: `sqlite3_vec_init` has the exact C signature SQLite expects for
16        // an extension entry point; the transmute is the pattern shipped in the
17        // upstream sqlite-vec crate's own tests.
18        rusqlite::ffi::sqlite3_auto_extension(Some(std::mem::transmute(
19            sqlite_vec::sqlite3_vec_init as *const (),
20        )));
21    });
22}
23
24/// Thin wrapper around `rusqlite::Connection` that guarantees the sqlite-vec
25/// extension is available and applies Paper's pragmas.
26pub struct Connection {
27    conn: rusqlite::Connection,
28}
29
30impl Connection {
31    /// Open an existing database file, running `PRAGMA quick_check` to verify
32    /// integrity before any work proceeds. If the file doesn't exist, it is
33    /// created with creation-time pragmas (page_size, etc.).
34    ///
35    /// `quick_check` is O(database size) and only runs on the first open after
36    /// creation; subsequent opens skip it since WAL mode guarantees crash
37    /// safety (I4: avoids per-search latency on large indexes).
38    pub fn open(path: &Path) -> Result<Self> {
39        register_sqlite_vec();
40        let existed = path.exists();
41        if let Some(parent) = path.parent() {
42            std::fs::create_dir_all(parent)
43                .with_context(|| format!("creating db directory {}", parent.display()))?;
44        }
45        let conn = rusqlite::Connection::open(path)
46            .with_context(|| format!("opening {}", path.display()))?;
47        if !existed {
48            // Fresh database: quick_check is instant on an empty file.
49            let quick_check: String = conn.query_row("PRAGMA quick_check", [], |row| row.get(0))?;
50            if quick_check != "ok" {
51                anyhow::bail!("database quick_check failed: {quick_check}");
52            }
53        }
54        Self::finish(conn, !existed) // set page_size only on fresh files
55    }
56
57    /// Open a database file that will be created if it doesn't exist. Runs
58    /// `PRAGMA quick_check` on the new/empty file (always "ok") and applies
59    /// creation-time pragmas like `page_size`.
60    ///
61    /// This is a convenience alias for `open`; both now handle fresh files.
62    pub fn open_or_create(path: &Path) -> Result<Self> {
63        Self::open(path)
64    }
65
66    pub fn open_in_memory() -> Result<Self> {
67        register_sqlite_vec();
68        let conn = rusqlite::Connection::open_in_memory()?;
69        Self::finish(conn, false) // in-memory DB cannot set page_size
70    }
71
72    /// Apply Paper's standard pragmas. `allow_page_size` controls whether
73    /// `PRAGMA page_size = 8192` is executed (only on fresh files, never on
74    /// existing databases — changing it requires VACUUM).
75    fn finish(conn: rusqlite::Connection, allow_page_size: bool) -> Result<Self> {
76        conn.busy_timeout(std::time::Duration::from_secs(5))?;
77        // WAL lets searches run while the indexer writes.
78        conn.execute_batch(
79            "PRAGMA journal_mode = WAL;
80             PRAGMA synchronous = NORMAL;
81             PRAGMA foreign_keys = ON;
82             PRAGMA mmap_size = 268435456;
83             PRAGMA wal_autocheckpoint = 1000;",
84        )?;
85        if allow_page_size {
86            // page_size must be set before any tables are created; it only takes
87            // effect on a fresh file. On an existing DB this is a no-op.
88            conn.execute_batch("PRAGMA page_size = 8192;")?;
89        }
90        Ok(Self { conn })
91    }
92
93    pub fn inner(&self) -> &rusqlite::Connection {
94        &self.conn
95    }
96
97    pub fn inner_mut(&mut self) -> &mut rusqlite::Connection {
98        &mut self.conn
99    }
100
101    pub fn execute_batch(&self, sql: &str) -> Result<()> {
102        self.conn.execute_batch(sql)?;
103        Ok(())
104    }
105
106    /// Convenience for scalar queries used by doctor/tests.
107    pub fn query_i64(&self, sql: &str) -> Result<i64> {
108        Ok(self.conn.query_row(sql, [], |row| row.get(0))?)
109    }
110
111    pub fn query_row<T, P: rusqlite::Params>(
112        &self,
113        sql: &str,
114        params: P,
115        f: impl FnOnce(&rusqlite::Row<'_>) -> rusqlite::Result<T>,
116    ) -> Result<T> {
117        Ok(self.conn.query_row(sql, params, f)?)
118    }
119
120    /// Get the embedding model ID stored in the index, if any.
121    pub fn stored_embedding_model(&self) -> Result<Option<String>> {
122        let model: Option<String> = self
123            .conn
124            .query_row(
125                "SELECT value FROM index_meta WHERE key = 'embedding_model'",
126                [],
127                |row| row.get(0),
128            )
129            .optional()?;
130        Ok(model)
131    }
132}