Expand description
Extension entry point helper.
Provides init_extension, the core helper called by the entry_point! macro.
§Problem 1: Custom C entry point
DuckDB’s Rust crate does not provide a safe way to obtain a raw
duckdb_connection handle for function registration. The prior approach
using extract_raw_connection relied on Rc<RefCell<InnerConnection>> layout,
causing SEGFAULTs. The correct approach is a hand-written C entry point that:
- Calls
duckdb_rs_extension_api_init(info, access, "v1.2.0") - Calls
access.get_database(info)to get aduckdb_database - Calls
duckdb_connect(db, &mut raw_con)to get aduckdb_connection - Registers all functions
- Calls
duckdb_disconnect(&mut raw_con)
§Pitfall L3: No panic across FFI
init_extension uses Result for all error propagation and never calls
unwrap() or panic!() inside an FFI callback.
§Registration is transactional
The registration connection is an ordinary connection, so the entry point
runs the closure inside BEGIN TRANSACTION on it, COMMITs when the
closure returns Ok and ROLLBACKs when it returns Err or panics
(Registration::Transactional, the default). Every registration the C API
makes through a connection joins that transaction. So a LOAD that fails
part-way leaves no catalog entry behind — no scalar, aggregate or table
function, macro, type, copy function or table the closure created — and
retrying it in the same database works. Before quack-rs 0.20 the functions
registered before the failure stayed, and every retry failed at the first
name it registered again.
What is not rolled back, because DuckDB keeps it in the database
configuration rather than the catalog: casts
(register_cast),
replacement scans and configuration options. A retry registers a cast
again (the new one replaces the old) and appends a second replacement
scan, and quack-rs refuses a configuration option whose name is taken, so
register those last, after everything that can fail.
What the transaction changes for the closure:
- A statement or registration that fails can abort the transaction
(
DuckDB2.0 aborts it on every failed statement; 1.x on most failures that are not binder, catalog or parser errors), after which every later statement in the closure fails with “Current transaction is aborted”. Return the first error rather than carrying on past it. - The closure must not run
BEGIN,COMMITorROLLBACKon the registration connection. - What the closure creates is visible to other connections only once the
LOADcommits, including a connection the closure opened itself withConnection::open_connection.
Choose Registration::Autocommit (through EntryPointOptions) to get
the old behaviour back: every statement commits on its own.
The transaction costs two statements, BEGIN and COMMIT, per LOAD.
A LOAD issued inside the host’s own transaction does not wait on it: the
registration connection is a separate connection with a transaction of its
own, which commits on its own (so the host rolling back does not undo the
registrations), and DuckDB’s catalog reports a conflicting write as an
error rather than waiting for the other transaction.
§panic = "abort" is refused at compile time
Every panic guard in quack-rs is std::panic::catch_unwind, which does
nothing when the extension is built with panic = "abort". So
entry_point! and entry_point_v2! fail to compile there, with an error
that names the fix (panic = "unwind" under [profile.release]). The check
runs in the extension’s crate, where the profile applies; an entry point
written by hand around init_extension_v2 has no such check.
Even under panic = "unwind" a few failures abort the DuckDB process
whatever quack-rs does: a panic while another panic unwinds (a Drop that
panics during the unwind), a panic hook that panics, and running out of
memory. See crate::callback.
§Edition 2024
The macros expand cleanly in an edition-2024 extension, and are written so
that they keep doing so once quack-rs itself moves to that edition
(#[unsafe(no_mangle)]):
use quack_rs::abi::AbiPolicy;
use quack_rs::error::ExtensionError;
fn register(_con: libduckdb_sys::duckdb_connection) -> Result<(), ExtensionError> {
Ok(())
}
quack_rs::entry_point!(a_init_c_api, |con| register(con));
quack_rs::entry_point!(b_init_c_api, AbiPolicy::Trust, |con| register(con));
quack_rs::entry_point_v2!(c_init_c_api, |_con| Ok(()));
quack_rs::entry_point_v2!(d_init_c_api, AbiPolicy::Warn, |_con| Ok(()));
quack_rs::entry_point_v2!(
e_init_c_api,
options = quack_rs::entry_point::EntryPointOptions::new(),
|_con| Ok(())
);§Usage
Extension authors typically use the entry_point! macro,
which generates the required #[unsafe(no_mangle)] extern "C" function automatically.
If you need full control over the entry point, you can call init_extension
directly:
use quack_rs::entry_point::init_extension;
#[unsafe(no_mangle)]
pub unsafe extern "C" fn my_extension_init_c_api(
info: libduckdb_sys::duckdb_extension_info,
access: *const libduckdb_sys::duckdb_extension_access,
) -> bool {
unsafe {
init_extension(info, access, quack_rs::DUCKDB_API_VERSION, |con| {
// register functions with `con: libduckdb_sys::duckdb_connection`
Ok(())
})
}
}Structs§
- Entry
Point Options - What an entry point is configured with: the
AbiPolicyand theRegistrationmode.
Enums§
- Registration
- How the entry point runs the registration closure.
Constants§
- EMPTY_
INIT_ ERROR_ PLACEHOLDER - What a load reports when the registration closure (or quack-rs’s own
setup) returned an
ExtensionErrorwith an empty message.
Functions§
- init_
extension ⚠ - Core entry point helper — sets up a connection and calls your registration closure.
- init_
extension_ ⚠v2 - Core entry point helper — sets up a
Connectionand calls your registration closure. - init_
extension_ ⚠v2_ with_ options init_extension_v2with explicitEntryPointOptions: theAbiPolicyand theRegistrationmode.- init_
extension_ ⚠v2_ with_ policy init_extension_v2with an explicitAbiPolicy.- init_
extension_ ⚠with_ options init_extensionwith explicitEntryPointOptions: theAbiPolicyand theRegistrationmode.- init_
extension_ ⚠with_ policy init_extensionwith an explicitAbiPolicy.