Skip to main content

quack_rs/
instance_cache.rs

1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tom F. <https://github.com/tomtom215/>
3// My way of giving something small back to the open source community
4// and encouraging more Rust development!
5
6//! Database instance cache (`DuckDB` 1.5.0+).
7//!
8//! An [`InstanceCache`] lets multiple connections share a single underlying
9//! `DuckDB` instance for a given database path. Opening the same path twice
10//! through the cache returns handles backed by the *same* instance, which avoids
11//! the "database is already open in another process/instance" conflict and saves
12//! the cost of re-initialising the database.
13//!
14//! This is primarily useful for extensions or host integrations that open
15//! secondary databases on behalf of a query.
16//!
17//! # Example
18//!
19//! ```rust,no_run
20//! use quack_rs::instance_cache::InstanceCache;
21//!
22//! # fn demo() -> Result<(), quack_rs::error::ExtensionError> {
23//! let cache = InstanceCache::new();
24//! // Returns a duckdb_database the caller owns and must close with duckdb_close.
25//! let db = cache.get_or_create(c"my.db", None)?;
26//! # let _ = db;
27//! # Ok(())
28//! # }
29//! ```
30
31use std::ffi::CStr;
32use std::os::raw::c_char;
33
34use libduckdb_sys::{
35    duckdb_config, duckdb_create_instance_cache, duckdb_database, duckdb_destroy_instance_cache,
36    duckdb_free, duckdb_get_or_create_from_cache, duckdb_instance_cache, DuckDBSuccess,
37};
38
39use crate::config::DbConfig;
40use crate::error::ExtensionError;
41
42/// RAII wrapper for a `duckdb_instance_cache`.
43///
44/// Automatically destroyed when dropped. A database obtained from the cache
45/// holds its own reference to the instance, so it stays valid after the cache
46/// is dropped, until it is closed.
47///
48/// # Threads
49///
50/// `InstanceCache` is `Send + Sync`: one cache can be shared by threads that
51/// open databases through it concurrently, which is what it is for.
52///
53/// One ordering hazard is `DuckDB`'s, not a data race: while the **last**
54/// handle to a cached file database is being closed, a concurrent
55/// [`get_or_create`][Self::get_or_create] for the same path can fail with
56/// "Unique file handle conflict ... is already attached" — the closing
57/// instance still holds the file. Keep one handle open for as long as other
58/// threads may open the path, or retry.
59pub struct InstanceCache {
60    cache: duckdb_instance_cache,
61}
62
63// SAFETY: the handle owns a heap-allocated `DBInstanceCacheWrapper` holding a
64// `duckdb::DBInstanceCache` (src/main/capi/duckdb-c.cpp). That object has no
65// thread affinity, so it may be dropped on any thread (`Send`). Its only
66// shared-state operation reachable through `&self` is
67// `duckdb_get_or_create_from_cache` → `DBInstanceCache::GetOrCreateInstance`,
68// which takes the cache's `mutex cache_lock` before it reads or writes the
69// `db_instances` map, and serialises creation of one database with that
70// entry's `update_database_mutex` (src/main/db_instance_cache.cpp,
71// src/include/duckdb/main/db_instance_cache.hpp). Concurrent calls through
72// shared references are therefore data-race free (`Sync`). The one argument it
73// mutates besides its own state is the `DBConfig` passed in; `DbConfig` is
74// neither `Send` nor `Sync`, so two threads cannot pass the same one.
75unsafe impl Send for InstanceCache {}
76// SAFETY: see the `Send` impl above.
77unsafe impl Sync for InstanceCache {}
78
79impl InstanceCache {
80    /// Creates a new, empty instance cache.
81    #[must_use]
82    pub fn new() -> Self {
83        // SAFETY: duckdb_create_instance_cache allocates an owned handle.
84        let cache = unsafe { duckdb_create_instance_cache() };
85        Self { cache }
86    }
87
88    /// Opens `path` through the cache, creating the instance if it does not yet
89    /// exist or returning a handle to the cached one if it does.
90    ///
91    /// Pass `config` to control how a freshly-created instance is configured.
92    /// When an instance already exists for `path`, `config` must match the one
93    /// it was created with: a different configuration is an error ("Can't open
94    /// a connection to same database file with a different configuration than
95    /// existing connections", `DBInstanceCache::GetInstanceInternal`), not
96    /// silently ignored. `None` means `DuckDB`'s defaults, so it too conflicts
97    /// with an instance created with a non-default `config`.
98    ///
99    /// An empty `path` (or `:memory:`) is never cached: each call creates a new,
100    /// separate in-memory database.
101    ///
102    /// The returned `duckdb_database` is owned by the caller and **must** be
103    /// closed with `duckdb_close` when no longer needed.
104    ///
105    /// # Errors
106    ///
107    /// Returns an [`ExtensionError`] carrying `DuckDB`'s message if the instance
108    /// cannot be opened or created, or if `config` conflicts with the cached
109    /// instance's.
110    pub fn get_or_create(
111        &self,
112        path: &CStr,
113        config: Option<&DbConfig>,
114    ) -> Result<duckdb_database, ExtensionError> {
115        let mut out_db: duckdb_database = std::ptr::null_mut();
116        let mut out_err: *mut c_char = std::ptr::null_mut();
117        let cfg: duckdb_config = config.map_or(std::ptr::null_mut(), DbConfig::as_raw);
118        // SAFETY: self.cache and path are valid; out_db and out_err are valid
119        // out-pointers; cfg is either null or a valid duckdb_config.
120        let state = unsafe {
121            duckdb_get_or_create_from_cache(
122                self.cache,
123                path.as_ptr(),
124                &raw mut out_db,
125                cfg,
126                &raw mut out_err,
127            )
128        };
129        if state == DuckDBSuccess && !out_db.is_null() {
130            return Ok(out_db);
131        }
132        let message = if out_err.is_null() {
133            "failed to open database from instance cache".to_owned()
134        } else {
135            // SAFETY: out_err is a valid null-terminated string allocated by DuckDB.
136            let msg = unsafe { CStr::from_ptr(out_err) }
137                .to_str()
138                .unwrap_or("failed to open database from instance cache")
139                .to_owned();
140            // SAFETY: out_err was allocated by DuckDB and must be freed.
141            unsafe { duckdb_free(out_err.cast()) };
142            msg
143        };
144        Err(ExtensionError::new(message))
145    }
146
147    /// Returns the raw handle.
148    #[inline]
149    #[must_use]
150    pub const fn as_raw(&self) -> duckdb_instance_cache {
151        self.cache
152    }
153}
154
155impl Default for InstanceCache {
156    fn default() -> Self {
157        Self::new()
158    }
159}
160
161impl Drop for InstanceCache {
162    fn drop(&mut self) {
163        if !self.cache.is_null() {
164            // SAFETY: self.cache is a valid handle that we own.
165            unsafe { duckdb_destroy_instance_cache(&raw mut self.cache) };
166        }
167    }
168}
169
170#[cfg(all(test, feature = "_duckdb-testing"))]
171mod tests {
172    use super::*;
173
174    #[test]
175    fn open_in_memory_via_cache() {
176        // Ensure the dispatch table is populated.
177        let _db = crate::testing::InMemoryDb::open().unwrap();
178
179        let cache = InstanceCache::new();
180        // Empty path opens an in-memory database.
181        let result = cache.get_or_create(c"", None);
182        assert!(result.is_ok(), "get_or_create failed: {:?}", result.err());
183        let mut db = result.unwrap();
184        // SAFETY: db is a valid duckdb_database returned from the cache.
185        unsafe { libduckdb_sys::duckdb_close(&raw mut db) };
186    }
187
188    /// Scratch database path unique to this test process.
189    fn scratch_db(tag: &str) -> std::ffi::CString {
190        let path = std::env::temp_dir().join(format!(
191            "quack_rs_instance_cache_{tag}_{}.duckdb",
192            std::process::id()
193        ));
194        let _ = std::fs::remove_file(&path);
195        std::ffi::CString::new(path.to_str().expect("utf-8 temp dir")).expect("no NUL")
196    }
197
198    /// TBL-13: the doc said a different config for an existing instance is
199    /// ignored; `DuckDB` rejects it.
200    #[test]
201    fn a_different_config_for_a_cached_instance_is_an_error() {
202        let _dispatch = crate::testing::InMemoryDb::open().unwrap();
203        let cache = InstanceCache::new();
204        let path = scratch_db("config");
205        let mut first = cache.get_or_create(&path, None).expect("first open");
206        let config = DbConfig::new().unwrap().set("threads", "1").unwrap();
207        let err = cache
208            .get_or_create(&path, Some(&config))
209            .expect_err("a conflicting config must be refused");
210        assert!(err.as_str().contains("different configuration"), "{err}");
211        // SAFETY: `first` came from the cache and is closed once.
212        unsafe { libduckdb_sys::duckdb_close(&raw mut first) };
213        let _ = std::fs::remove_file(path.to_str().unwrap_or_default());
214    }
215
216    /// TBL-25: a cache can be shared across threads.
217    #[test]
218    fn one_cache_serves_concurrent_threads() {
219        fn assert_send_sync<T: Send + Sync>() {}
220        assert_send_sync::<InstanceCache>();
221
222        let _dispatch = crate::testing::InMemoryDb::open().unwrap();
223        let cache = InstanceCache::new();
224        let path = scratch_db("threads");
225        // Every thread opens, then waits until all have opened before any
226        // closes: closing the last handle while another thread opens the
227        // same path is a DuckDB-level conflict (see "Threads").
228        let opened = std::sync::Barrier::new(4);
229        std::thread::scope(|scope| {
230            for _ in 0..4 {
231                scope.spawn(|| {
232                    let mut db = cache
233                        .get_or_create(&path, None)
234                        .expect("open from a thread");
235                    opened.wait();
236                    // SAFETY: `db` came from the cache and is closed once.
237                    unsafe { libduckdb_sys::duckdb_close(&raw mut db) };
238                });
239            }
240        });
241        let _ = std::fs::remove_file(path.to_str().unwrap_or_default());
242    }
243}
244
245crate::debug_repr::impl_handle_debug!(InstanceCache.cache);