Prepared Statements

Functions
kdbc_stmt *	kdbc_prepare (kdbc_conn *conn, const char *sql)
	Prepare a SQL statement.
kdbc_stmt *	kdbc_prepare_returning (kdbc_conn *conn, const char *sql, const char **col_names, int n_cols)
	Prepare a SQL statement that returns generated keys.
int	kdbc_bind_null (kdbc_stmt *stmt, int idx)
	Bind a NULL value to a parameter.
int	kdbc_bind_int (kdbc_stmt *stmt, int idx, int val)
	Bind a 32-bit integer parameter.
int	kdbc_bind_bool (kdbc_stmt *stmt, int idx, int val)
	Bind a boolean parameter.
int	kdbc_bind_long (kdbc_stmt *stmt, int idx, int64_t val)
	Bind a 64-bit integer parameter.
int	kdbc_bind_double (kdbc_stmt *stmt, int idx, double val)
	Bind a double-precision float parameter.
int	kdbc_bind_string (kdbc_stmt *stmt, int idx, const char *val)
	Bind a UTF-8 string parameter.
int	kdbc_bind_blob (kdbc_stmt *stmt, int idx, const void *data, size_t len)
	Bind a binary blob parameter.
int	kdbc_bind_timestamp (kdbc_stmt *stmt, int idx, int year, int month, int day, int hour, int minute, int second, int usec)
	Bind a timestamp (date + time) parameter.
int	kdbc_bind_date (kdbc_stmt *stmt, int idx, int year, int month, int day)
	Bind a date-only parameter.
int	kdbc_bind_time (kdbc_stmt *stmt, int idx, int hour, int minute, int second, int usec)
	Bind a time-only parameter.

Detailed Description

Prepare SQL, bind parameters, and manage statement lifecycle.

Use ? as parameter placeholders — KDBC translates them automatically:

• PostgreSQL: $1, $2, ...
• Oracle: :1, :2, ...
• SQLite, MariaDB, MSSQL: kept as ?

All parameter indices are 1-indexed.

kdbc_stmt *stmt = kdbc_prepare(conn, "INSERT INTO users (name, age) VALUES (?, ?)");
kdbc_bind_string(stmt, 1, "Alice");
kdbc_bind_int(stmt, 2, 30);
int rows = kdbc_execute_update_stmt(stmt);
kdbc_stmt_close(stmt);

Function Documentation

kdbc_prepare()

kdbc_stmt * kdbc_prepare	(	kdbc_conn *	conn,
		const char *	sql )

Prepare a SQL statement.

Parameters

conn	An open connection.
sql	SQL with ? parameter placeholders.

Returns

A prepared statement handle, or NULL on failure.

kdbc_prepare_returning()

kdbc_stmt * kdbc_prepare_returning	(	kdbc_conn *	conn,
		const char *	sql,
		const char **	col_names,
		int	n_cols )

Prepare a SQL statement that returns generated keys.

Used for INSERT statements when you need to retrieve auto-generated primary keys. The mechanism varies by database:

• PostgreSQL / Oracle 12c+: appends RETURNING col1, col2, ...
• MSSQL: uses OUTPUT INSERTED.col1, ...
• SQLite / MariaDB: uses last_insert_rowid() / LAST_INSERT_ID()

Parameters

conn	An open connection.
sql	SQL with ? parameter placeholders.
col_names	Array of column names to return (may be NULL for index-based drivers).
n_cols	Number of entries in col_names (0 if NULL).

Returns

A prepared statement handle, or NULL on failure.

See also

kdbc_generated_keys()

kdbc_bind_null()

int kdbc_bind_null	(	kdbc_stmt *	stmt,
		int	idx )

Bind a NULL value to a parameter.

Parameters

stmt	A prepared statement.
idx	Parameter index (1-indexed).

Returns

KDBC_OK or KDBC_ERROR.

kdbc_bind_int()

int kdbc_bind_int	(	kdbc_stmt *	stmt,
		int	idx,
		int	val )

Bind a 32-bit integer parameter.

Parameters

stmt	A prepared statement.
idx	Parameter index (1-indexed).
val	The integer value.

Returns

KDBC_OK or KDBC_ERROR.

kdbc_bind_bool()

int kdbc_bind_bool	(	kdbc_stmt *	stmt,
		int	idx,
		int	val )

Bind a boolean parameter.

On databases with native BOOLEAN support (e.g. PostgreSQL), this binds as a true boolean. On all others, it binds as an integer (0 or 1).

Parameters

stmt	A prepared statement.
idx	Parameter index (1-indexed).
val	The boolean value (0 = false, non-zero = true).

Returns

KDBC_OK or KDBC_ERROR.

kdbc_bind_long()

int kdbc_bind_long	(	kdbc_stmt *	stmt,
		int	idx,
		int64_t	val )

Bind a 64-bit integer parameter.

Parameters

stmt	A prepared statement.
idx	Parameter index (1-indexed).
val	The int64 value.

Returns

KDBC_OK or KDBC_ERROR.

kdbc_bind_double()

int kdbc_bind_double	(	kdbc_stmt *	stmt,
		int	idx,
		double	val )

Bind a double-precision float parameter.

Parameters

stmt	A prepared statement.
idx	Parameter index (1-indexed).
val	The double value.

Returns

KDBC_OK or KDBC_ERROR.

kdbc_bind_string()

int kdbc_bind_string	(	kdbc_stmt *	stmt,
		int	idx,
		const char *	val )

Bind a UTF-8 string parameter.

The string is copied internally — the caller may free val immediately.

Parameters

stmt	A prepared statement.
idx	Parameter index (1-indexed).
val	The null-terminated UTF-8 string.

Returns

KDBC_OK or KDBC_ERROR.

kdbc_bind_blob()

int kdbc_bind_blob	(	kdbc_stmt *	stmt,
		int	idx,
		const void *	data,
		size_t	len )

Bind a binary blob parameter.

The data is copied internally — the caller may free data immediately.

Parameters

stmt	A prepared statement.
idx	Parameter index (1-indexed).
data	Pointer to the binary data.
len	Length of data in bytes.

Returns

KDBC_OK or KDBC_ERROR.

kdbc_bind_timestamp()

int kdbc_bind_timestamp	(	kdbc_stmt *	stmt,
		int	idx,
		int	year,
		int	month,
		int	day,
		int	hour,
		int	minute,
		int	second,
		int	usec )

Bind a timestamp (date + time) parameter.

No timezone — treated as local time. Each driver converts to its native temporal format internally.

Parameters

stmt	A prepared statement.
idx	Parameter index (1-indexed).
year	Year (e.g. 2024).
month	Month (1–12).
day	Day (1–31).
hour	Hour (0–23).
minute	Minute (0–59).
second	Second (0–59).
usec	Microseconds (0–999999).

Returns

KDBC_OK or KDBC_ERROR.

kdbc_bind_date()

int kdbc_bind_date	(	kdbc_stmt *	stmt,
		int	idx,
		int	year,
		int	month,
		int	day )

Bind a date-only parameter.

Parameters

stmt	A prepared statement.
idx	Parameter index (1-indexed).
year	Year.
month	Month (1–12).
day	Day (1–31).

Returns

KDBC_OK or KDBC_ERROR.

kdbc_bind_time()

int kdbc_bind_time	(	kdbc_stmt *	stmt,
		int	idx,
		int	hour,
		int	minute,
		int	second,
		int	usec )

Bind a time-only parameter.

Parameters

stmt	A prepared statement.
idx	Parameter index (1-indexed).
hour	Hour (0–23).
minute	Minute (0–59).
second	Second (0–59).
usec	Microseconds (0–999999).

Returns

KDBC_OK or KDBC_ERROR.