kdbc.h File Reference

KDBC Native — Unified C Database Connectivity. More...

#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Macros
#define	KDBC_OK   0
#define	KDBC_ERROR   (-1)

Typedefs
typedef struct kdbc_conn	kdbc_conn
	Opaque database connection handle.
typedef struct kdbc_stmt	kdbc_stmt
	Opaque prepared statement handle.
typedef struct kdbc_result	kdbc_result
	Opaque result set handle.

Enumerations
enum	kdbc_driver {   KDBC_SQLITE = 0 , KDBC_POSTGRES = 1 , KDBC_MARIADB = 2 , KDBC_ORACLE = 3 ,   KDBC_MSSQL = 4 , KDBC_DRIVER_COUNT = 5 }
	Supported database drivers. More...
enum	kdbc_type {   KDBC_TYPE_NULL = 0 , KDBC_TYPE_INT = 1 , KDBC_TYPE_LONG = 2 , KDBC_TYPE_DOUBLE = 3 ,   KDBC_TYPE_STRING = 4 , KDBC_TYPE_BLOB = 5 , KDBC_TYPE_BOOL = 6 , KDBC_TYPE_DATE = 7 ,   KDBC_TYPE_TIME = 8 , KDBC_TYPE_TIMESTAMP = 9 }
	Column / parameter value types. More...
enum	kdbc_gk_strategy { KDBC_GK_NONE = 0 , KDBC_GK_BY_INDEX = 1 , KDBC_GK_BY_NAME = 2 }
	Generated-key retrieval strategies. More...

Functions
int	kdbc_driver_available (kdbc_driver driver)
	Check if a driver's native library is available on this system.
const char *	kdbc_driver_name (kdbc_driver driver)
	Get the human-readable name of a driver.
kdbc_gk_strategy	kdbc_driver_gk_strategy (kdbc_driver driver)
	Get the default generated-key strategy for a driver.
kdbc_gk_strategy	kdbc_conn_gk_strategy (kdbc_conn *conn)
	Get the generated-key strategy for an open connection.
int	kdbc_driver_supports_release_savepoint (kdbc_driver driver)
	Check if a driver supports RELEASE SAVEPOINT.
const char *	kdbc_error (kdbc_conn *conn)
	Get the last error message for a connection.
const char *	kdbc_stmt_error (kdbc_stmt *stmt)
	Get the last error message for a statement.
const char *	kdbc_global_error (void)
	Get the last global (connection-less) error message.
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.
int	kdbc_execute_update (kdbc_conn *conn, const char *sql)
	Execute a non-parameterized DML/DDL statement directly.
kdbc_result *	kdbc_execute_query (kdbc_conn *conn, const char *sql)
	Execute a non-parameterized SELECT directly.
int	kdbc_set_autocommit (kdbc_conn *conn, int enabled)
	Enable or disable autocommit.
int	kdbc_commit (kdbc_conn *conn)
	Commit the current transaction.
int	kdbc_rollback (kdbc_conn *conn)
	Roll back the current transaction.
int	kdbc_savepoint (kdbc_conn *conn, const char *name)
	Create a savepoint.
int	kdbc_rollback_to (kdbc_conn *conn, const char *name)
	Roll back to a savepoint.
int	kdbc_release_savepoint (kdbc_conn *conn, const char *name)
	Release a savepoint.
const char *	kdbc_product_name (kdbc_conn *conn)
	Get the database product name (e.g. "SQLite", "PostgreSQL").
const char *	kdbc_product_version (kdbc_conn *conn)
	Get the full database version string.
int	kdbc_major_version (kdbc_conn *conn)
	Get the major version number.
int	kdbc_minor_version (kdbc_conn *conn)
	Get the minor version number.
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.
int	kdbc_execute_update_stmt (kdbc_stmt *stmt)
	Execute a prepared DML statement (INSERT/UPDATE/DELETE).
kdbc_result *	kdbc_execute_query_stmt (kdbc_stmt *stmt)
	Execute a prepared query (SELECT).
kdbc_result *	kdbc_generated_keys (kdbc_stmt *stmt)
	Get generated keys after an INSERT.
void	kdbc_stmt_close (kdbc_stmt *stmt)
	Close a prepared statement and free resources.
int	kdbc_stmt_reset (kdbc_stmt *stmt)
	Reset a prepared statement for re-execution.
int	kdbc_set_fetch_size (kdbc_stmt *stmt, int rows)
	Set a fetch size hint for query execution.
int	kdbc_add_batch (kdbc_stmt *stmt)
	Add current parameters as a batch entry.
int	kdbc_execute_batch (kdbc_stmt *stmt)
	Execute all batched parameter sets.
kdbc_stmt *	kdbc_prepare_call (kdbc_conn *conn, const char *sql)
	Prepare a stored procedure call.
int	kdbc_register_out (kdbc_stmt *stmt, int idx)
	Register a parameter as OUT.
int	kdbc_call_execute (kdbc_stmt *stmt)
	Execute a callable statement.
int64_t	kdbc_call_get_long (kdbc_stmt *stmt, int idx)
	Retrieve an OUT parameter as a 64-bit integer.
const char *	kdbc_call_get_string (kdbc_stmt *stmt, int idx)
	Retrieve an OUT parameter as a string.
int	kdbc_next (kdbc_result *rs)
	Advance to the next row.
int	kdbc_col_count (kdbc_result *rs)
	Get the number of columns in the result set.
const char *	kdbc_col_name (kdbc_result *rs, int col)
	Get a column name by index.
const char *	kdbc_col_label (kdbc_result *rs, int col)
	Get a column label (alias) by index.
int	kdbc_is_null (kdbc_result *rs, int col)
	Check if a column value is NULL.
int64_t	kdbc_get_long (kdbc_result *rs, int col)
	Get a column value as a 64-bit integer.
double	kdbc_get_double (kdbc_result *rs, int col)
	Get a column value as a double.
const char *	kdbc_get_string (kdbc_result *rs, int col)
	Get a column value as a UTF-8 string.
const void *	kdbc_get_blob (kdbc_result *rs, int col, size_t *out_len)
	Get a column value as a binary blob.
int	kdbc_get_timestamp (kdbc_result *rs, int col, int *year, int *month, int *day, int *hour, int *minute, int *second, int *usec)
	Get a column value as a timestamp (date + time).
int	kdbc_get_date (kdbc_result *rs, int col, int *year, int *month, int *day)
	Get a column value as a date (no time component).
int	kdbc_get_time (kdbc_result *rs, int col, int *hour, int *minute, int *second, int *usec)
	Get a column value as a time (no date component).
void	kdbc_result_close (kdbc_result *rs)
	Close a result set and free resources.

Detailed Description

KDBC Native — Unified C Database Connectivity.

A lightweight C library that provides a common API for multiple database backends (SQLite, PostgreSQL, MariaDB/MySQL, Oracle, MSSQL). Libraries are loaded at runtime via dlopen, so missing backends are handled gracefully — only the drivers you actually use need to be installed.

Key design points:

• Opaque handles: all state is behind kdbc_conn, kdbc_stmt, kdbc_result
• Runtime driver loading: native client libraries are loaded via dlopen/LoadLibrary at first use — no link-time dependency on any database client
• JDBC-style placeholders: use ? in SQL — automatically translated to $1/$2 (PostgreSQL), :1/:2 (Oracle), or kept as ? (SQLite, MariaDB, MSSQL)
• 1-indexed: all column and parameter indices start at 1

Copyright

(C) Panayotis Katsaloulis SPDX-License-Identifier: Apache-2.0