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);