Skip to main content

InstanceCache

Struct InstanceCache 

Source
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

Source

pub fn new() -> Self

Creates a new, empty instance cache.

Source

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.

Source

pub const fn as_raw(&self) -> duckdb_instance_cache

Returns the raw handle.

Trait Implementations§

Source§

impl Debug for InstanceCache

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for InstanceCache

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl Drop for InstanceCache

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more
Source§

impl Send for InstanceCache

Source§

impl Sync for InstanceCache

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.