Connection Management

Functions
kdbc_conn *	kdbc_connect (kdbc_driver driver, const char *url, const char *user, const char *password)
	Open a database connection.
void	kdbc_close (kdbc_conn *conn)
	Close a connection and free all associated resources.
kdbc_driver	kdbc_conn_driver (kdbc_conn *conn)
	Get the driver type of a connection.
int	kdbc_cancel (kdbc_conn *conn)
	Cancel a running statement from another thread.

Detailed Description

Open, close, and manage database connections.

Function Documentation

kdbc_connect()

kdbc_conn * kdbc_connect	(	kdbc_driver	driver,
		const char *	url,
		const char *	user,
		const char *	password )

Open a database connection.

The URL format depends on the driver:

Driver	URL format	Example
KDBC_SQLITE	File path or :memory:	/tmp/test.db
KDBC_POSTGRES	host:port/database	localhost:5432/mydb
KDBC_MARIADB	host:port/database	localhost:3306/mydb
KDBC_ORACLE	host:port/service_name	localhost:1521/XEPDB1
KDBC_MSSQL	host:port/database	localhost:1433/mydb

Parameters

driver	The database driver to use.
url	Connection URL (format varies by driver — see table above).
user	Username (ignored for SQLite — pass NULL).
password	Password (ignored for SQLite — pass NULL).

Returns

A new connection handle, or NULL on failure. On failure, call kdbc_global_error() for details.

kdbc_close()

void kdbc_close

(

kdbc_conn *

conn

)

Close a connection and free all associated resources.

Safe to call with NULL (no-op).

Parameters

conn	The connection to close, or NULL.

kdbc_conn_driver()

kdbc_driver kdbc_conn_driver

(

kdbc_conn *

conn

)

Get the driver type of a connection.

Parameters

conn	An open connection.

Returns

The driver enum value.

kdbc_cancel()

int kdbc_cancel

(

kdbc_conn *

conn

)

Cancel a running statement from another thread.

Best-effort asynchronous cancellation of any statement currently executing on this connection. Designed to be called from a thread other than the one blocked inside a KDBC call — this is the mechanism by which higher-level code (e.g. a coroutine cancellation handler) can interrupt a running query.

When the cancel takes effect, the blocking call on the other thread will return with KDBC_ERROR and a driver-specific error message.

Each driver dispatches to the underlying library's async-cancel primitive:

• PostgreSQL: PQcancel
• SQLite: sqlite3_interrupt
• Oracle: dpiConn_breakExecution
• MariaDB: mariadb_cancel
• MSSQL: ct_cancel

Warning

Thread safety: safe to call concurrently with a blocking KDBC call on the same connection. Not safe to call concurrently with kdbc_close() on the same connection.

Parameters

conn	The connection whose running statement should be cancelled.

Returns

KDBC_OK if the cancel request was dispatched, KDBC_ERROR if conn is NULL, the driver doesn't support cancellation, or the underlying primitive reported a failure.