sqlrite.h

// Auto-generated by cbindgen from sqlrite-ffi/src/lib.rs.
// Do not edit by hand — changes will be overwritten on the next build.
//
// This is the C ABI for the SQLRite embedded database engine. Every
// non-Rust SDK (Python / Node.js / Go / raw C) binds against the same
// functions declared here. See sqlrite-ffi/src/lib.rs for the full
// memory-ownership and error-handling rules.

#ifndef SQLRITE_H
#define SQLRITE_H

#pragma once

#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>

// Return value of every mutating FFI function. `Ok` is zero; every
// error is a distinct positive integer so bindings can switch on it.
// The full error message (with path / SQL / nested causes) is
// available via [`sqlrite_last_error`].
typedef enum SqlriteStatus {
  Ok = 0,
  // Generic error — check `sqlrite_last_error` for details.
  Error = 1,
  // A required pointer argument was null, or an input string was
  // invalid UTF-8 / not NUL-terminated.
  InvalidArgument = 2,
  // Phase 11.7 — a `BEGIN CONCURRENT` commit hit a row-level
  // write-write conflict. The transaction has already been
  // rolled back; the caller should retry the whole
  // transaction with a fresh `BEGIN CONCURRENT`. SDK retry
  // helpers branch on this code (or its `BusySnapshot`
  // sibling) and call their user-provided closure again.
  Busy = 5,
  // Phase 11.7 — same retry semantics as [`Self::Busy`], but
  // surfaces the snapshot-isolation specific case (a row in
  // the transaction's read-set changed under us). Reserved
  // for the read-anomaly path Phase 11.5+ wires through
  // `MvStore`; today the engine emits it from the same
  // `BEGIN CONCURRENT` commit path. Distinguished from
  // `Busy` so SDKs can map each to its own
  // per-language exception class without forking on the
  // message string.
  BusySnapshot = 6,
  // A SELECT query returned no more rows (returned from `step`).
  Done = 101,
  // A SELECT query produced a row (returned from `step`).
  Row = 102,
} SqlriteStatus;

// Opaque handle to a SQLRite database connection.
typedef struct SqlriteConnection {
  uint8_t _private[0];
} SqlriteConnection;

// Opaque handle to a running SELECT query. Yields rows via
// [`sqlrite_step`] until `SqlriteStatus::Done`.
typedef struct SqlriteStatement {
  uint8_t _private[0];
} SqlriteStatement;

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

// Returns the last error message raised on the current thread, or
// `NULL` if the most recent call succeeded. The returned pointer is
// owned by the library (thread-local storage) and stays valid until
// the next FFI call on the same thread — do *not* pass it to
// [`sqlrite_free_string`].
//
// # Safety
//
// The caller must not mutate or free the returned pointer.
const char *sqlrite_last_error(void);

// Opens (or creates) a database file for read-write access.
//
// On success, `*out` is set to a non-null handle and the return value
// is `SqlriteStatus::Ok`. On failure, `*out` is left null and the
// return value is an error status; call [`sqlrite_last_error`] for
// the message.
//
// # Safety
//
// `path` must be a valid NUL-terminated UTF-8 string. `out` must be a
// valid writable pointer. The caller owns the returned connection
// and must free it with [`sqlrite_close`].
enum SqlriteStatus sqlrite_open(const char *path, struct SqlriteConnection **out);

// Opens an existing database file for read-only access — takes a
// shared advisory lock so multiple read-only openers coexist.
//
// # Safety
//
// Same as [`sqlrite_open`].
enum SqlriteStatus sqlrite_open_read_only(const char *path, struct SqlriteConnection **out);

// Opens a transient in-memory database — no file, no locks. Useful
// for tests and short-lived in-process DBs.
//
// # Safety
//
// `out` must be a valid writable pointer.
enum SqlriteStatus sqlrite_open_in_memory(struct SqlriteConnection **out);

// Phase 11.8 — mints a sibling connection that shares the same
// underlying database state (the in-memory tables, the MVCC
// store, the pager). Wraps the engine's `Connection::connect`.
//
// Use this to drive `BEGIN CONCURRENT` from multiple FFI
// handles: each sibling can hold its own concurrent transaction,
// and commits validate against the shared MvStore.
//
// The returned handle is owned by the caller and must be freed
// with [`sqlrite_close`]; closing one sibling doesn't affect
// the others.
//
// # Safety
//
// `existing` must be a valid pointer returned by one of the
// `sqlrite_open_*` functions and not yet closed. `out` must be
// a valid writable pointer. On success the caller owns the
// returned sibling and must call [`sqlrite_close`] on it when
// done.
enum SqlriteStatus sqlrite_connect_sibling(struct SqlriteConnection *existing,
                                           struct SqlriteConnection **out);

// Closes a connection and releases its file locks. Safe to call with
// a null pointer (no-op).
//
// # Safety
//
// `conn` must be a pointer returned by one of the `sqlrite_open_*`
// functions and not yet closed. After this call the pointer is
// invalid.
void sqlrite_close(struct SqlriteConnection *conn);

// Parses and executes a single SQL statement that doesn't produce
// rows (CREATE / INSERT / UPDATE / DELETE / BEGIN / COMMIT /
// ROLLBACK). Use [`sqlrite_query`] for SELECT.
//
// # Safety
//
// `conn` must be a valid open connection handle. `sql` must be a
// valid NUL-terminated UTF-8 string.
enum SqlriteStatus sqlrite_execute(struct SqlriteConnection *conn, const char *sql);

// Parses and runs a SELECT, returning a statement handle whose rows
// are iterated via [`sqlrite_step`]. Errors if the SQL isn't a
// SELECT.
//
// # Safety
//
// `conn` must be a valid open connection handle. `sql` must be a
// valid NUL-terminated UTF-8 string. `out` must be a valid writable
// pointer. On success the caller owns the returned statement and
// must call [`sqlrite_finalize`] when done.
enum SqlriteStatus sqlrite_query(struct SqlriteConnection *conn,
                                 const char *sql,
                                 struct SqlriteStatement **out);

// Advances the statement to the next row.
//
// Returns:
// - `SqlriteStatus::Row` — a row is available; read columns via the
//   `sqlrite_column_*` accessors.
// - `SqlriteStatus::Done` — the query is exhausted; stop calling step.
// - any error code — check `sqlrite_last_error`.
//
// # Safety
//
// `stmt` must be a valid statement handle returned by
// [`sqlrite_query`] and not yet finalized.
enum SqlriteStatus sqlrite_step(struct SqlriteStatement *stmt);

// Frees a statement handle.
//
// # Safety
//
// `stmt` must be a pointer returned by [`sqlrite_query`] and not
// yet finalized. After this call the pointer is invalid.
void sqlrite_finalize(struct SqlriteStatement *stmt);

// Number of columns in the current row. Writes the count to `*out`
// and returns `Ok`, or an error status if no row is active.
//
// # Safety
//
// `stmt` must be a valid statement handle. `out` must be a valid
// writable pointer.
enum SqlriteStatus sqlrite_column_count(struct SqlriteStatement *stmt, int *out);

// Writes the name of column `idx` into `*out` as a heap-allocated
// NUL-terminated string. The caller must free it via
// [`sqlrite_free_string`].
//
// # Safety
//
// Same as [`sqlrite_column_count`].
enum SqlriteStatus sqlrite_column_name(struct SqlriteStatement *stmt, int idx, char **out);

// Reads column `idx` of the current row as a 64-bit integer into `*out`.
// Errors if no row is active, the column is NULL, or the column's
// native type can't be losslessly converted to i64.
//
// # Safety
//
// Same as [`sqlrite_column_count`].
enum SqlriteStatus sqlrite_column_int64(struct SqlriteStatement *stmt, int idx, int64_t *out);

// Reads column `idx` as a double.
enum SqlriteStatus sqlrite_column_double(struct SqlriteStatement *stmt, int idx, double *out);

// Reads column `idx` as a newly-allocated NUL-terminated UTF-8
// string. The caller must free the result via [`sqlrite_free_string`].
enum SqlriteStatus sqlrite_column_text(struct SqlriteStatement *stmt, int idx, char **out);

// Writes `1` to `*out` if column `idx` is NULL, `0` otherwise.
enum SqlriteStatus sqlrite_column_is_null(struct SqlriteStatement *stmt, int idx, int *out);

// Returns 1 if a `BEGIN … COMMIT/ROLLBACK` block is open on this
// connection, 0 otherwise. -1 on error (null handle).
//
// # Safety
//
// `conn` must be a valid open connection handle (or null, in which
// case this returns -1).
int sqlrite_in_transaction(struct SqlriteConnection *conn);

// Returns 1 if this connection was opened read-only, 0 otherwise.
// -1 on error.
int sqlrite_is_read_only(struct SqlriteConnection *conn);

// Generate SQL from a natural-language question via the configured
// LLM provider. Returns a JSON string in `*out` (caller frees with
// `sqlrite_free_string`).
//
// `config_json` may be NULL or an empty string to use
// `AskConfig::from_env()`. Otherwise it's a JSON object with any of
// the documented keys above; unset keys fall back to env values.
//
// # Safety
//
// `conn` must be a valid open connection handle. `question` must be
// a valid NUL-terminated UTF-8 string. `config_json` may be NULL or
// a valid NUL-terminated UTF-8 JSON string. `out` must be a valid
// writable pointer.
enum SqlriteStatus sqlrite_ask(struct SqlriteConnection *conn,
                               const char *question,
                               const char *config_json,
                               char **out);

// Frees a string returned by `sqlrite_column_text` or `sqlrite_column_name`.
// Safe to call with a null pointer (no-op).
//
// # Safety
//
// `ptr` must be a pointer returned by one of those functions and not
// yet freed.
void sqlrite_free_string(char *ptr);

#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus

#endif  /* SQLRITE_H */