Skip to main content

Module entry_point

Module entry_point 

Source
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:

  1. Calls duckdb_rs_extension_api_init(info, access, "v1.2.0")
  2. Calls access.get_database(info) to get a duckdb_database
  3. Calls duckdb_connect(db, &mut raw_con) to get a duckdb_connection
  4. Registers all functions
  5. 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 (DuckDB 2.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, COMMIT or ROLLBACK on the registration connection.
  • What the closure creates is visible to other connections only once the LOAD commits, including a connection the closure opened itself with Connection::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§

EntryPointOptions
What an entry point is configured with: the AbiPolicy and the Registration mode.

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 ExtensionError with 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 Connection and calls your registration closure.
init_extension_v2_with_options⚠
init_extension_v2 with explicit EntryPointOptions: the AbiPolicy and the Registration mode.
init_extension_v2_with_policy⚠
init_extension_v2 with an explicit AbiPolicy.
init_extension_with_options⚠
init_extension with explicit EntryPointOptions: the AbiPolicy and the Registration mode.
init_extension_with_policy⚠
init_extension with an explicit AbiPolicy.