Skip to main content

OwnedConnection

Struct OwnedConnection 

Source
pub struct OwnedConnection { /* private fields */ }
Expand description

A duckdb_connection this crate opened and will disconnect on drop.

Open one during registration when the extension needs to run SQL later — from a background thread, or from a callback, where the C API offers no way back to a connection. A connection created from the load-time duckdb_database holds a shared_ptr to the database instance, so it outlives extension loading.

This is not the connection DuckDB passes to your entry point; that one is borrowed and is disconnected when registration returns.

Implementations§

Source§

impl OwnedConnection

Source

pub unsafe fn open(db: duckdb_database) -> Result<Self, ExtensionError>

Opens a new connection to db.

§Errors

Returns ExtensionError if DuckDB refuses to open the connection.

§Safety

db must be a valid duckdb_database, such as the one obtained from Connection::as_raw_database.

Source

pub fn query(&self, sql: &str) -> Result<QueryResult, ExtensionError>

Runs sql on this connection.

§Errors

See query.

Source

pub fn execute(&self, sql: &str) -> Result<u64, ExtensionError>

Runs sql for its side effects, returning the number of rows changed.

§Errors

See query.

Source

pub fn prepare(&self, sql: &str) -> Result<PreparedStatement, ExtensionError>

Prepares sql on this connection.

§Errors

See prepare.

Source

pub const fn interrupt_handle(&self) -> InterruptHandle<'_>

Returns a Send + Sync handle for cancelling a query running on this connection, or reading its progress, from another thread.

The handle borrows the connection, so it cannot outlive the duckdb_disconnect in Drop.

Source

pub fn interrupt(&self)

Requests cancellation of whatever this connection is currently running.

See interrupt for what “cancellation” means here. To cancel from another thread, use interrupt_handle.

Source

pub fn progress(&self) -> QueryProgress

Reads the progress of whatever this connection is currently running.

Source

pub const fn as_raw(&self) -> duckdb_connection

Returns the raw handle. Do not disconnect it — this value still owns it.

Source

pub const unsafe fn from_raw(con: duckdb_connection) -> Self

Takes ownership of a raw connection, which is then disconnected (duckdb_disconnect) on drop.

§Safety

con must be a live connection from duckdb_connect that nothing else disconnects. In particular not the connection DuckDB passes to an extension’s entry point (Connection::as_raw_connection): that one is borrowed, and the entry point disconnects it.

§Example
use quack_rs::query::OwnedConnection;

let mut raw: libduckdb_sys::duckdb_connection = std::ptr::null_mut();
// SAFETY: `db` is open.
if unsafe { libduckdb_sys::duckdb_connect(db, &raw mut raw) } == libduckdb_sys::DuckDBSuccess {
    // SAFETY: a fresh connection owned by nothing else.
    let con = unsafe { OwnedConnection::from_raw(raw) };
    let _ = con.execute("SELECT 1");
}
Source

pub const fn into_raw(self) -> duckdb_connection

Gives up ownership and returns the raw connection, which the caller must disconnect (duckdb_disconnect) or hand back to from_raw.

Source

pub fn table_names( &self, sql: &str, qualified: bool, ) -> Result<Vec<String>, ExtensionError>

The tables sql reads or writes; see table_names (DuckDB 1.5.0+).

§Errors

See table_names.

Trait Implementations§

Source§

impl Debug for OwnedConnection

Source§

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

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

impl Drop for OwnedConnection

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 OwnedConnection

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.