Home /Modules/db-connector/sldbc.h

sldbc.h

lib/db-connector/include/sldbc.h · 128 line(s) · c

/*
 * lib/db-connector/include/sldbc.h
 *
 * SLeeLa DB Connector -- the SLeeLa equivalent of JDBC + a driver.
 *
 * Java has a database API (java.sql.*) plus pluggable DRIVERS shipped as jars
 * (e.g. the PostgreSQL connector jar). SLeeLa has the same split:
 *
 *   - lib/database (.sleela)       : the API SHAPE (SLDatabase, SLResultSet...)
 *   - this connector (sldbc_*)     : the driver manager + driver contract
 *   - lib/sleela-sql (ssql_*)      : a concrete backend the first driver targets
 *
 * This header is the driver-agnostic connector ABI. A program opens a
 * connection by URL (e.g. "sleelasql:./data"), prepares statements, binds
 * positional parameters, executes, and iterates result rows -- exactly the
 * JDBC lifecycle, in C. The bundled "sleelasql" driver wraps the local
 * lib/sleela-sql engine; other backends (PostgreSQL, MySQL, ...) are registered
 * by name but return SLDBC_UNSUPPORTED until a real driver is written, so the
 * connector never pretends to support a database it cannot actually reach.
 */
#ifndef SLEELA_SLDBC_H
#define SLEELA_SLDBC_H

#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

typedef enum {
  SLDBC_OK = 0,
  SLDBC_ERR_ARG = -1,        /* bad argument                         */
  SLDBC_ERR_URL = -2,        /* malformed connection URL             */
  SLDBC_ERR_NODRIVER = -3,   /* no driver registered for that scheme */
  SLDBC_UNSUPPORTED = -4,    /* driver is a stub / op not supported  */
  SLDBC_ERR_OPEN = -5,       /* backend failed to open               */
  SLDBC_ERR_EXEC = -6,       /* statement failed                     */
  SLDBC_ERR_RANGE = -7,      /* row/column index out of range        */
  SLDBC_ERR_OOM = -8         /* allocation failed                    */
} sldbc_status;

/* Opaque handles (JDBC: Connection, PreparedStatement, ResultSet). */
typedef struct sldbc_conn sldbc_conn;
typedef struct sldbc_stmt sldbc_stmt;
typedef struct sldbc_rows sldbc_rows;

/* ---- driver manager -------------------------------------------------- */

/*
 * Open a connection. `url` is "<scheme>:<target>" -- e.g. "sleelasql:./data".
 * The scheme selects the driver; the target is driver-specific (for sleelasql
 * it is the database directory). On success *out holds a connection the caller
 * must sldbc_close().
 */
sldbc_status sldbc_open(const char *url, sldbc_conn **out);

/* Close a connection (finalizes nothing the caller still holds). Safe on NULL. */
void sldbc_close(sldbc_conn *c);

/* The driver (scheme) name backing a connection, e.g. "sleelasql". */
const char *sldbc_driver_name(const sldbc_conn *c);

/* Is a scheme backed by a real (non-stub) driver? 1 yes, 0 stub/unknown. */
int sldbc_driver_available(const char *scheme);

/* ---- statements ------------------------------------------------------ */

/*
 * Prepare `sql` (SQL or fluent SLeeLaSQL; '?' positional placeholders). On
 * success *out holds a statement the caller must sldbc_finalize().
 */
sldbc_status sldbc_prepare(sldbc_conn *c, const char *sql, sldbc_stmt **out);

/* Bind a value to placeholder `index` (1-based, like JDBC). Value is copied. */
sldbc_status sldbc_bind(sldbc_stmt *s, int index, const char *value);

/* Clear all bound values so the statement can be re-bound and re-run. */
void sldbc_clear(sldbc_stmt *s);

/*
 * Execute a statement that returns no rows (INSERT/UPDATE/DELETE/CREATE/...).
 * Returns SLDBC_OK or an error.
 */
sldbc_status sldbc_execute(sldbc_stmt *s);

/*
 * Execute a query and capture its result set. On success *out holds a row set
 * the caller must sldbc_rows_free(). Works for SELECT / SHOW TABLES.
 */
sldbc_status sldbc_query(sldbc_stmt *s, sldbc_rows **out);

/* Release a prepared statement. Safe on NULL. */
void sldbc_finalize(sldbc_stmt *s);

/* ---- result sets (JDBC: ResultSet) ----------------------------------- */

size_t sldbc_rows_count(const sldbc_rows *r);     /* number of data rows   */
size_t sldbc_rows_columns(const sldbc_rows *r);   /* number of columns     */
const char *sldbc_rows_column_name(const sldbc_rows *r, size_t col);

/*
 * Cell value at (row, col), or NULL if out of range. The returned pointer is
 * owned by the row set and valid until sldbc_rows_free().
 */
const char *sldbc_rows_value(const sldbc_rows *r, size_t row, size_t col);

/* Value by column name in a given row; NULL if the column is absent. */
const char *sldbc_rows_value_named(const sldbc_rows *r, size_t row,
                                   const char *column);

void sldbc_rows_free(sldbc_rows *r);

/* ---- transactions (JDBC: setAutoCommit(false)/commit/rollback) ------- */

sldbc_status sldbc_begin(sldbc_conn *c);
sldbc_status sldbc_commit(sldbc_conn *c);
sldbc_status sldbc_rollback(sldbc_conn *c);

/* ---- diagnostics ----------------------------------------------------- */

const char *sldbc_strerror(sldbc_status s);
const char *sldbc_version(void);

#ifdef __cplusplus
}
#endif
#endif /* SLEELA_SLDBC_H */