Home /Modules/sleela-sql/sleela_sql.h

sleela_sql.h

lib/sleela-sql/native/include/sleela_sql.h · 168 line(s) · c

/*
 * sleela_sql.h -- a simple CSV-backed MySQL-subset engine (C API).
 *
 * Part of mearvk/Nintendo. This is a self-contained, dependency-free SQL
 * engine: every table is a plain CSV file on disk (header row = column names,
 * one data row per record). It ships no copyrighted content.
 *
 * The division of labour mirrors the Professional Editor: this C engine does
 * the byte/file I/O (parsing statements, reading and writing CSV), while the
 * SLeeLa counterpart in /lib/sleela-sql owns the *model and validation* layer.
 *
 * TWO DIALECTS, ONE ENGINE
 * ------------------------
 * Every database statement can be written in either of two surface languages,
 * and both compile to the SAME internal operation and run on the SAME executor:
 *
 *   1. SQL          -- the familiar MySQL-flavoured subset.
 *   2. SLeeLaSQL    -- a clean, fluent, method-chaining dialect that mirrors
 *                      SLeeLa's own syntax (see docs/SLEELASQL.md). It is
 *                      feature-complete with the SQL subset: anything you can
 *                      say in SQL you can say in SLeeLaSQL and vice-versa.
 *
 * PREPARED STATEMENTS (the speed-up)
 * ----------------------------------
 * A statement in EITHER dialect can be *compiled once* into an ssql_stmt and
 * then executed many times with different bound values. Placeholders are '?'
 * (positional) in both dialects. Compiling once and re-binding avoids
 * re-parsing on every call -- the same win a real DB's PreparedStatement gives.
 */
#ifndef SLEELA_SQL_H
#define SLEELA_SQL_H

#include <stddef.h>
#include <stdio.h>

#ifdef __cplusplus
extern "C" {
#endif

#define SSQL_MAX_COLS   64
#define SSQL_MAX_FIELD  512

typedef enum {
    SSQL_OK = 0,
    SSQL_ERR_IO       = -1,  /* file could not be read or written           */
    SSQL_ERR_SYNTAX   = -2,  /* the statement did not parse                 */
    SSQL_ERR_NOTABLE  = -3,  /* table (CSV file) does not exist             */
    SSQL_ERR_EXISTS   = -4,  /* CREATE on an existing table                 */
    SSQL_ERR_NOCOL    = -5,  /* referenced a column the table does not have */
    SSQL_ERR_ARITY    = -6,  /* INSERT value count != column count          */
    SSQL_ERR_ARG      = -7,  /* bad argument                                */
    SSQL_ERR_BIND     = -8,  /* unbound placeholder / bad bind index        */
    SSQL_ERR_OOM      = -9,  /* allocation failed                           */
    SSQL_ERR_DUPCOL   = -10  /* ALTER TABLE column already exists            */
} ssql_status;

/* Which surface language a statement was written in. */
typedef enum {
    SSQL_DIALECT_AUTO = 0,   /* sniff: SLeeLaSQL if it looks fluent, else SQL */
    SSQL_DIALECT_SQL,        /* force classic SQL                             */
    SSQL_DIALECT_SLEELA      /* force SLeeLaSQL                                */
} ssql_dialect;

/* An engine instance: all tables live as <name>.csv under `dir`. */
typedef struct {
    char dir[SSQL_MAX_FIELD]; /* directory holding the .csv table files */
} ssql_db;

/* A compiled statement (prepared, dialect-agnostic). Opaque; heap-owned. */
typedef struct ssql_stmt ssql_stmt;

/* ---- database lifecycle ---------------------------------------------- */

/* Open (or create) a database rooted at a directory. */
ssql_status ssql_open(ssql_db *db, const char *dir);

/* ---- one-shot execution ---------------------------------------------- */

/*
 * Parse and execute a single statement in `text`. The dialect is auto-detected.
 * Any row output (SELECT / SHOW TABLES) is written to `out` as CSV; pass NULL
 * to discard. Equivalent to prepare + run + finalize with no bound values.
 */
ssql_status ssql_exec(ssql_db *db, const char *text, FILE *out);

/* As ssql_exec, but force a specific dialect (no sniffing). */
ssql_status ssql_exec_dialect(ssql_db *db, const char *text,
                              ssql_dialect dialect, FILE *out);

/* ALTER TABLE ADD COLUMN is available in the classic SQL dialect. Existing rows receive DEFAULT value or an empty string. */

/* ---- prepared statements (both dialects) ----------------------------- */

/*
 * Compile `text` (in the given dialect; AUTO sniffs) into a reusable statement.
 * On success *out_stmt holds a heap object the caller must ssql_finalize().
 * The compile happens once; execute it repeatedly with ssql_run().
 */
ssql_status ssql_prepare(ssql_db *db, const char *text,
                         ssql_dialect dialect, ssql_stmt **out_stmt);

/* Number of '?' placeholders in a prepared statement. */
int ssql_param_count(const ssql_stmt *stmt);

/*
 * Bind a value to placeholder `index` (1-based, like JDBC/SQLite). The value is
 * copied. Re-binding the same index overwrites. Call ssql_reset to clear all.
 */
ssql_status ssql_bind(ssql_stmt *stmt, int index, const char *value);

/* Clear all bound values so the statement can be re-bound and re-run. */
void ssql_reset(ssql_stmt *stmt);

/*
 * Execute a prepared statement with the currently-bound values. Row output is
 * written to `out` as CSV (NULL to discard). May be called many times; call
 * ssql_reset / ssql_bind between calls to change the bound values.
 */
ssql_status ssql_run(ssql_stmt *stmt, FILE *out);

/* Release a prepared statement. Safe on NULL. */
void ssql_finalize(ssql_stmt *stmt);

/* ---- transactions (snapshot-based) ----------------------------------- */

/*
 * A deliberately-modest, HONEST first transaction API with documented
 * guarantees (ROADMAP Priority A). This is SNAPSHOT-based, single-connection
 * rollback -- NOT full ACID and NOT multi-writer isolation:
 *
 *   ssql_begin(db)    : take a snapshot of every table (.csv) in the database
 *                       directory into a journal subdirectory. One active
 *                       transaction per database directory.
 *   ssql_commit(db)   : accept the current on-disk state; discard the snapshot.
 *   ssql_rollback(db) : restore every table from the snapshot, undoing all
 *                       statements executed since ssql_begin, then discard it.
 *
 * Guarantees it DOES provide: after a successful ssql_begin, a subsequent
 * ssql_rollback returns the table files to exactly their begin-time contents
 * (atomic at the API level for a single caller). Tables created after begin are
 * removed on rollback; tables dropped after begin are restored.
 *
 * Guarantees it does NOT yet provide (see ROADMAP): crash recovery (a process
 * crash mid-transaction leaves the journal for manual recovery, not automatic
 * replay), isolation between concurrent writers, and nested transactions.
 * Do not advertise ACID until the journal/recovery and isolation items land.
 */
ssql_status ssql_begin(ssql_db *db);
ssql_status ssql_commit(ssql_db *db);
ssql_status ssql_rollback(ssql_db *db);

/* Nonzero if a transaction is currently open on this database directory. */
int ssql_in_transaction(const ssql_db *db);

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

/* Human-readable message for a status code. */
const char *ssql_strerror(ssql_status s);

/* Name of a dialect ("sql" / "sleelasql" / "auto"). */
const char *ssql_dialect_name(ssql_dialect d);

#ifdef __cplusplus
}
#endif

#endif /* SLEELA_SQL_H */