pub struct InstanceCache { /* private fields */ }Expand description
RAII wrapper for a duckdb_instance_cache.
Automatically destroyed when dropped. A database obtained from the cache holds its own reference to the instance, so it stays valid after the cache is dropped, until it is closed.
§Threads
InstanceCache is Send + Sync: one cache can be shared by threads that
open databases through it concurrently, which is what it is for.
One ordering hazard is DuckDB’s, not a data race: while the last
handle to a cached file database is being closed, a concurrent
get_or_create for the same path can fail with
“Unique file handle conflict … is already attached” — the closing
instance still holds the file. Keep one handle open for as long as other
threads may open the path, or retry.
Implementations§
Source§impl InstanceCache
impl InstanceCache
Sourcepub fn get_or_create(
&self,
path: &CStr,
config: Option<&DbConfig>,
) -> Result<duckdb_database, ExtensionError>
pub fn get_or_create( &self, path: &CStr, config: Option<&DbConfig>, ) -> Result<duckdb_database, ExtensionError>
Opens path through the cache, creating the instance if it does not yet
exist or returning a handle to the cached one if it does.
Pass config to control how a freshly-created instance is configured.
When an instance already exists for path, config must match the one
it was created with: a different configuration is an error (“Can’t open
a connection to same database file with a different configuration than
existing connections”, DBInstanceCache::GetInstanceInternal), not
silently ignored. None means DuckDB’s defaults, so it too conflicts
with an instance created with a non-default config.
An empty path (or :memory:) is never cached: each call creates a new,
separate in-memory database.
The returned duckdb_database is owned by the caller and must be
closed with duckdb_close when no longer needed.
§Errors
Returns an ExtensionError carrying DuckDB’s message if the instance
cannot be opened or created, or if config conflicts with the cached
instance’s.