Tiny ORM over a SQL socket stream. More...

#include <stdbool.h>
#include <stdint.h>
#include <cwist/sys/err/cwist_err.h>
#include <cjson/cJSON.h>

Include dependency graph for orm.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	cwist_orm_value
	One cell of a column-typed result set. More...

struct	cwist_orm_result
	Column-typed result set produced by cwist_orm_query_typed(). More...

Macros
#define	cwist_orm_insert_r(orm, table, data, returning_col, out)
	Type-generic INSERT with RETURNING clause.

#define	cwist_orm_select_one(orm, table, column, where, out)
	Type-generic SELECT a single scalar value.

Typedefs
typedef struct cwist_orm	cwist_orm_t
	Opaque ORM session handle.

typedef enum cwist_orm_dialect	cwist_orm_dialect_t
	Supported SQL dialects for query generation.

typedef enum cwist_orm_value_type	cwist_orm_value_type_t
	Storage class of a typed result cell.

typedef struct cwist_orm_value	cwist_orm_value_t
	One cell of a column-typed result set.

typedef struct cwist_orm_result	cwist_orm_result_t
	Column-typed result set produced by cwist_orm_query_typed().

Enumerations
enum	cwist_orm_dialect { CWIST_ORM_SQLITE , CWIST_ORM_POSTGRES , CWIST_ORM_MYSQL , CWIST_ORM_MARIADB }
	Supported SQL dialects for query generation. More...

enum	cwist_orm_value_type { CWIST_ORM_TYPE_NULL = 0 , CWIST_ORM_TYPE_INTEGER , CWIST_ORM_TYPE_REAL , CWIST_ORM_TYPE_TEXT , CWIST_ORM_TYPE_BLOB }
	Storage class of a typed result cell. More...

Functions
cwist_orm_t *	cwist_orm_open_socket (int socket_fd)
	Create an ORM session from an existing SQL socket.

void	cwist_orm_close_socket (cwist_orm_t *orm)
	Destroy an ORM session and close its underlying socket.

void	cwist_orm_immediate_commit (bool enable)
	Toggle automatic commit mode.

void	cwist_orm_use_dialect (cwist_orm_t *orm, cwist_orm_dialect_t dialect)
	Select the SQL dialect used for query generation.

cwist_error_t	cwist_orm_commit (cwist_orm_t *orm)
	Commit the current transaction.

cwist_error_t	cwist_orm_rollback (cwist_orm_t *orm)
	Roll back the current transaction.

cwist_error_t	cwist_orm_exec (cwist_orm_t orm, const char sql)
	Execute a non-query SQL statement.

cwist_error_t	cwist_orm_query (cwist_orm_t orm, const char sql, cJSON **result)
	Execute a SELECT query and return the result set.

cwist_error_t	cwist_orm_insert (cwist_orm_t orm, const char table, const cJSON *data)
	Insert a JSON object into a table.

cwist_error_t	cwist_orm_update (cwist_orm_t orm, const char table, const cJSON data, const char where_clause)
	Update rows in a table.

cwist_error_t	cwist_orm_delete (cwist_orm_t orm, const char table, const char *where_clause)
	Delete rows from a table.

cwist_error_t	cwist_orm_select (cwist_orm_t orm, const char table, const char columns, const char where_clause, cJSON **result)
	Convenience SELECT helper.

cwist_error_t	cwist_orm_insert_returning_json (cwist_orm_t orm, const char table, const cJSON data, const char returning_col, cJSON **out)
	Insert a row and return a JSON value from the new row.

cwist_error_t	cwist_orm_insert_returning_int (cwist_orm_t orm, const char table, const cJSON data, const char returning_col, int *out)
	Insert a row and return a column value as an int.

cwist_error_t	cwist_orm_insert_returning_long (cwist_orm_t orm, const char table, const cJSON data, const char returning_col, long *out)
	Insert a row and return a column value as a long.

cwist_error_t	cwist_orm_insert_returning_llong (cwist_orm_t orm, const char table, const cJSON data, const char returning_col, long long *out)
	Insert a row and return a column value as a long long.

cwist_error_t	cwist_orm_query_typed (cwist_orm_t orm, const char sql, cwist_orm_result_t **result)
	Execute a SELECT-style query and return column-typed rows.

void	cwist_orm_result_free (cwist_orm_result_t *result)
	Release a result set from cwist_orm_query_typed().

size_t	cwist_orm_result_column_index (const cwist_orm_result_t result, const char column)
	Find a column index by name in a typed result set.

const cwist_orm_value_t *	cwist_orm_result_cell (const cwist_orm_result_t *result, size_t row, size_t column)
	Read one cell of a typed result set.

cwist_error_t	cwist_orm_select_one_json (cwist_orm_t orm, const char table, const char column, const char where_clause, cJSON **out)
	Select a single column value from the first matching row as JSON.

cwist_error_t	cwist_orm_select_one_int (cwist_orm_t orm, const char table, const char column, const char where_clause, int *out)
	Select a single column value from the first matching row as an int.

cwist_error_t	cwist_orm_select_one_long (cwist_orm_t orm, const char table, const char column, const char where_clause, long *out)
	Select a single column value from the first matching row as a long.

cwist_error_t	cwist_orm_select_one_llong (cwist_orm_t orm, const char table, const char column, const char where_clause, long long *out)
	Select a single column value from the first matching row as a long long.

cwist_error_t	cwist_orm_select_one_double (cwist_orm_t orm, const char table, const char column, const char where_clause, double *out)
	Select a single column value from the first matching row as a double.

cwist_error_t	cwist_orm_select_one_string (cwist_orm_t orm, const char table, const char column, const char where_clause, char **out)
	Select a single column value from the first matching row as a string.

cwist_error_t	cwist_orm_select_one_i64 (cwist_orm_t orm, const char table, const char column, const char where_clause, int64_t *out)
	Select a single integer cell exactly as an int64_t.

cwist_error_t	cwist_orm_insert_returning_i64 (cwist_orm_t orm, const char table, const cJSON data, const char returning_col, int64_t *out)
	Insert a row and return an integer column exactly as an int64_t.

Detailed Description

Tiny ORM over a SQL socket stream.

This header provides a socket-backed ORM interface. It intentionally never includes sqlite3.h; all communication with the SQL backend happens through a Unix domain socket obtained from cwist_db_transfer_sqlite_to_socket().

The default transaction mode is manual (immediate commit disabled). Call cwist_orm_immediate_commit(true) to make every write operation automatically commit.

Values in the cJSON data objects are escaped and table/column names are quoted before they reach the SQL text. Raw SQL arguments are not: sql in cwist_orm_exec() / cwist_orm_query(), every where_clause, and the columns list of cwist_orm_select() are inserted verbatim. Do not build those strings from untrusted input.

Definition in file orm.h.

Macro Definition Documentation

◆ cwist_orm_insert_r

#define cwist_orm_insert_r	(	orm,
		table,
		data,
		returning_col,
		out
	)

Value:

    _Generic((out),                                              \
        int *: cwist_orm_insert_returning_int,                   \
        long *: cwist_orm_insert_returning_long,                 \
        long long *: cwist_orm_insert_returning_llong,           \
        cJSON **: cwist_orm_insert_returning_json)((orm), (table), (data), (returning_col), (out))

Type-generic INSERT with RETURNING clause.

Dispatches to the appropriate typed helper based on the type of out.

Example:

int id;
cwist_orm_insert_r(orm, "users", row, "id", &id);
 
cJSON *obj;
cwist_orm_insert_r(orm, "users", row, "*", &obj);

Definition at line 260 of file orm.h.

◆ cwist_orm_select_one

#define cwist_orm_select_one	(	orm,
		table,
		column,
		where,
		out
	)

Value:

    _Generic((out),                                          \
        int *: cwist_orm_select_one_int,                     \
        long *: cwist_orm_select_one_long,                   \
        long long *: cwist_orm_select_one_llong,             \
        double *: cwist_orm_select_one_double,               \
        char **: cwist_orm_select_one_string,                \
        cJSON **: cwist_orm_select_one_json)((orm), (table), (column), (where), (out))

Type-generic SELECT a single scalar value.

Builds SELECT column FROM table [WHERE where_clause] LIMIT 1 and writes the first cell into out according to its C type.

The caller must free a char* or cJSON* result.

Example:

int age;

cwist_orm_select_one(orm, "users", "age", "id = 1", &age);

cwist_orm_select_one

#define cwist_orm_select_one(orm, table, column, where, out)

Type-generic SELECT a single scalar value.

Definition orm.h:453

Definition at line 453 of file orm.h.

Typedef Documentation

◆ cwist_orm_dialect_t

typedef enum cwist_orm_dialect cwist_orm_dialect_t

Supported SQL dialects for query generation.

◆ cwist_orm_result_t

typedef struct cwist_orm_result cwist_orm_result_t

Column-typed result set produced by cwist_orm_query_typed().

Cells are stored row-major: cell (row, column) lives at cells[row * column_count + column]. Column names come from the result-producing statement. Everything is released by cwist_orm_result_free().

◆ cwist_orm_t

typedef struct cwist_orm cwist_orm_t

Opaque ORM session handle.

Definition at line 36 of file orm.h.

◆ cwist_orm_value_t

typedef struct cwist_orm_value cwist_orm_value_t

One cell of a column-typed result set.

Exactly one payload field is meaningful per cwist_orm_value_type_t: i64 for CWIST_ORM_TYPE_INTEGER (exact above 2^53), real for CWIST_ORM_TYPE_REAL, text for CWIST_ORM_TYPE_TEXT (never NULL), and (blob, blob_len) for CWIST_ORM_TYPE_BLOB (blob is NULL when the BLOB is empty). Owned by the result set; released by cwist_orm_result_free().

◆ cwist_orm_value_type_t

typedef enum cwist_orm_value_type cwist_orm_value_type_t

Storage class of a typed result cell.

The class comes from the SQLite value's storage class (sqlite3_column_type()), not from its text: a TEXT column holding canonical integer text is CWIST_ORM_TYPE_TEXT, and SQL NULL is CWIST_ORM_TYPE_NULL, distinct from an empty TEXT value.

Enumeration Type Documentation

◆ cwist_orm_dialect

enum cwist_orm_dialect

Supported SQL dialects for query generation.

Enumerator
CWIST_ORM_SQLITE	SQLite dialect (default)
CWIST_ORM_POSTGRES	PostgreSQL dialect
CWIST_ORM_MYSQL	MySQL dialect
CWIST_ORM_MARIADB	MariaDB dialect

Definition at line 39 of file orm.h.

◆ cwist_orm_value_type

enum cwist_orm_value_type

Storage class of a typed result cell.

The class comes from the SQLite value's storage class (sqlite3_column_type()), not from its text: a TEXT column holding canonical integer text is CWIST_ORM_TYPE_TEXT, and SQL NULL is CWIST_ORM_TYPE_NULL, distinct from an empty TEXT value.

Enumerator
CWIST_ORM_TYPE_NULL	SQL NULL
CWIST_ORM_TYPE_INTEGER	INTEGER, exact through the full int64 range
CWIST_ORM_TYPE_REAL	REAL as a double
CWIST_ORM_TYPE_TEXT	TEXT as a null-terminated string
CWIST_ORM_TYPE_BLOB	BLOB as (blob, blob_len) bytes

Definition at line 279 of file orm.h.

Function Documentation

◆ cwist_orm_close_socket()

void cwist_orm_close_socket ( cwist_orm_t * orm )

Destroy an ORM session and close its underlying socket.

If a transaction is still open, it is rolled back before the socket is closed. The pointer is invalid after this call.

Parameters

orm	ORM handle created with cwist_orm_open_socket().

Destroy an ORM session and close its underlying socket.

Issues a best-effort ROLLBACK to discard any dangling transaction, then closes the socket descriptor and frees the handle. Safe to call with NULL.

Parameters

orm	Session to close (may be NULL).

Definition at line 163 of file orm.c.

References cap.

◆ cwist_orm_commit()

cwist_error_t cwist_orm_commit ( cwist_orm_t * orm )

Commit the current transaction.

Has no effect when immediate commit is enabled.

Parameters

orm	Active ORM session.

Returns: cwist_error_t with err_i16 == 0 on success, or CWIST_ERROR_IO on socket failure.

Parameters

orm	Active session.

Returns: CWIST_SUCCESS on success, otherwise an error code.

Definition at line 211 of file orm.c.

References cap, and cwist_orm_exec().

◆ cwist_orm_delete()

cwist_error_t cwist_orm_delete	(	cwist_orm_t *	orm,
		const char *	table,
		const char *	where_clause
	)

Delete rows from a table.

Parameters

orm	ORM session.
table	Target table name.
where_clause	Optional SQL predicate (without `WHERE`), or `NULL` to delete every row.

Returns: cwist_error_t with err_i16 == 0 on success.

If where_clause is non-empty it is appended as a WHERE clause; a NULL or empty clause deletes all rows.

Parameters

orm	Active session.
table	Table name.
where_clause	Optional raw SQL WHERE condition (not escaped).

Returns: CWIST_SUCCESS on success; CWIST_ERROR_INVALID_PARAM for NULL arguments, CWIST_ERROR_NOMEM on allocation failure, otherwise the error from cwist_orm_exec().

Definition at line 727 of file orm.c.

References cap, CWIST_ERR_INT16, CWIST_ERROR_INVALID_PARAM, CWIST_ERROR_NOMEM, cwist_orm_exec(), and make_error().

◆ cwist_orm_exec()

cwist_error_t cwist_orm_exec	(	cwist_orm_t *	orm,
		const char *	sql
	)

Execute a non-query SQL statement.

Suitable for INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, BEGIN, COMMIT, ROLLBACK, and any other statement that does not return result rows.

When immediate commit mode is active and the statement is a write operation, a COMMIT is automatically issued afterwards.

Parameters

orm	ORM session.
sql	Null-terminated SQL statement.

Returns: cwist_error_t with err_i16 == 0 on success, or a negative error code on failure (CWIST_ERROR_IO, CWIST_ERROR_PROTOCOL, etc.).

Execute a non-query SQL statement.

If immediate-commit mode is enabled, an INSERT/UPDATE/DELETE statement is followed by an automatic COMMIT.

Parameters

orm	Active session.
sql	Null-terminated SQL statement.

Returns: CWIST_SUCCESS on success; CWIST_ERROR_INVALID_PARAM for NULL arguments, CWIST_ERROR_IO on transport failure, or CWIST_ERROR_PROTOCOL when the backend reports an error.

Definition at line 241 of file orm.c.

References cap, CWIST_ERR_INT16, CWIST_ERROR_INVALID_PARAM, CWIST_ERROR_IO, CWIST_ERROR_PROTOCOL, CWIST_SUCCESS, and make_error().

Referenced by cwist_orm_commit(), cwist_orm_delete(), cwist_orm_insert(), cwist_orm_rollback(), and cwist_orm_update().

◆ cwist_orm_immediate_commit()

void cwist_orm_immediate_commit ( bool enable )

Toggle automatic commit mode.

When enabled, every cwist_orm_insert(), cwist_orm_update(), cwist_orm_delete(), and cwist_orm_exec() automatically appends a COMMIT statement so that the change is persisted immediately.

When disabled (the default), the caller is responsible for wrapping operations in explicit transactions via cwist_orm_commit() or cwist_orm_rollback().

Parameters

enable true to enable auto-commit, false to disable.

Toggle automatic commit mode.

Sessions opened afterwards inherit this value; existing sessions are not affected. When enabled, INSERT/UPDATE/DELETE statements executed through cwist_orm_exec() are followed by an automatic COMMIT.

Parameters

enable true to enable immediate commit, false to disable.

Definition at line 188 of file orm.c.

References cap.

◆ cwist_orm_insert()

cwist_error_t cwist_orm_insert	(	cwist_orm_t *	orm,
		const char *	table,
		const cJSON *	data
	)

Insert a JSON object into a table.

Scans data for keys and values, builds an INSERT statement, and executes it. Nested objects or arrays inside data are stringified with cJSON_PrintUnformatted().

Example:

cJSON *row = cJSON_Parse("{\"name\":\"Alice\",\"age\":30}");

cwist_orm_insert(orm, "users", row);

cwist_orm_insert

cwist_error_t cwist_orm_insert(cwist_orm_t *orm, const char *table, const cJSON *data)

Insert a JSON object into a table.

Definition orm.c:586

Parameters

orm	ORM session.
table	Target table name (used verbatim; must be sanitized by the caller if it comes from untrusted input).
data	cJSON object (not array) containing the row data.

Returns: cwist_error_t with err_i16 == 0 on success.

Column names and values are taken from the object's keys/values and rendered according to the session dialect.

Parameters

orm	Active session.
table	Table name.
data	JSON object with column names as keys.

Returns: CWIST_SUCCESS on success; CWIST_ERROR_INVALID_PARAM for NULL arguments or a non-object data, CWIST_ERROR_NOMEM on allocation failure, otherwise the error from cwist_orm_exec().

Definition at line 586 of file orm.c.

References cap, CWIST_ERR_INT16, CWIST_ERROR_INVALID_PARAM, CWIST_ERROR_NOMEM, cwist_orm_exec(), and make_error().

◆ cwist_orm_insert_returning_i64()

cwist_error_t cwist_orm_insert_returning_i64	(	cwist_orm_t *	orm,
		const char *	table,
		const cJSON *	data,
		const char *	returning_col,
		int64_t *	out
	)

Insert a row and return an integer column exactly as an int64_t.

Same statement as cwist_orm_insert_returning_llong(), with the returned value read as in cwist_orm_select_one_i64().

Returns: As cwist_orm_select_one_i64(); CWIST_ERROR_NOMEM when the SQL cannot be built.

Definition at line 1404 of file orm.c.

References cap, CWIST_ERR_INT16, CWIST_ERROR_INVALID_PARAM, CWIST_ERROR_NOMEM, and make_error().

◆ cwist_orm_insert_returning_int()

cwist_error_t cwist_orm_insert_returning_int	(	cwist_orm_t *	orm,
		const char *	table,
		const cJSON *	data,
		const char *	returning_col,
		int *	out
	)

Insert a row and return a column value as an int.

Parameters

orm	Active session.
table	Table name.
data	cJSON object with the column values to insert.
returning_col	Column (or alias) of the value to return.
out	[out] Receives the value as an int.

Returns: CWIST_SUCCESS on success; otherwise the error from cwist_orm_insert_returning_json() or CWIST_ERROR_PROTOCOL when the returned value is not a number.

Definition at line 932 of file orm.c.

References cap, CWIST_ERROR_PROTOCOL, and cwist_orm_insert_returning_json().

◆ cwist_orm_insert_returning_json()

cwist_error_t cwist_orm_insert_returning_json	(	cwist_orm_t *	orm,
		const char *	table,
		const cJSON *	data,
		const char *	returning_col,
		cJSON **	out
	)

Insert a row and return a JSON value from the new row.

Appends a dialect-specific RETURNING clause (or an equivalent last-insert-id follow-up query) to the INSERT built from data, then extracts the returning_col value from the first result row. For MySQL/SQLite the returned value is the last insert id, not an arbitrary column.

Parameters

orm	Active session.
table	Table name.
data	cJSON object with the column values to insert.
returning_col	Column (or alias) of the value to return.
out	[out] Receives a duplicated cJSON value; caller must release with cJSON_Delete().

Returns: CWIST_SUCCESS on success; CWIST_ERROR_INVALID_PARAM for NULL arguments, CWIST_ERROR_NOMEM on allocation failure, CWIST_ERROR_PROTOCOL when the value is missing from the result.

Definition at line 872 of file orm.c.

References cap, CWIST_ERR_INT16, CWIST_ERROR_INVALID_PARAM, CWIST_ERROR_NOMEM, CWIST_ERROR_PROTOCOL, cwist_orm_query(), and make_error().

Referenced by cwist_orm_insert_returning_int(), cwist_orm_insert_returning_llong(), and cwist_orm_insert_returning_long().

◆ cwist_orm_insert_returning_llong()

cwist_error_t cwist_orm_insert_returning_llong	(	cwist_orm_t *	orm,
		const char *	table,
		const cJSON *	data,
		const char *	returning_col,
		long long *	out
	)

Insert a row and return a column value as a long long.

Parameters

orm	Active session.
table	Table name.
data	cJSON object with the column values to insert.
returning_col	Column (or alias) of the value to return.
out	[out] Receives the value as a long long.

Returns: CWIST_SUCCESS on success; otherwise the error from cwist_orm_insert_returning_json() or CWIST_ERROR_PROTOCOL when the returned value is not a number.

Definition at line 985 of file orm.c.

References cap, CWIST_ERROR_PROTOCOL, and cwist_orm_insert_returning_json().

◆ cwist_orm_insert_returning_long()

cwist_error_t cwist_orm_insert_returning_long	(	cwist_orm_t *	orm,
		const char *	table,
		const cJSON *	data,
		const char *	returning_col,
		long *	out
	)

Insert a row and return a column value as a long.

Parameters

orm	Active session.
table	Table name.
data	cJSON object with the column values to insert.
returning_col	Column (or alias) of the value to return.
out	[out] Receives the value as a long.

Returns: CWIST_SUCCESS on success; otherwise the error from cwist_orm_insert_returning_json() or CWIST_ERROR_PROTOCOL when the returned value is not a number.

Definition at line 958 of file orm.c.

References cap, CWIST_ERROR_PROTOCOL, and cwist_orm_insert_returning_json().

◆ cwist_orm_open_socket()

cwist_orm_t * cwist_orm_open_socket ( int socket_fd )

Create an ORM session from an existing SQL socket.

The socket must have been produced by cwist_db_transfer_sqlite_to_socket() or by an equivalent SQL-socket factory. The ORM object takes ownership of socket_fd and will close it on cwist_orm_close_socket().

Parameters

socket_fd Valid connected Unix socket file descriptor.

Returns: Pointer to an initialized cwist_orm_t, or NULL on allocation failure.

Create an ORM session from an existing SQL socket.

Takes ownership of socket_fd: the descriptor is closed by cwist_orm_close_socket(). The session inherits the current global immediate-commit default and defaults to the SQLite dialect.

Parameters

socket_fd Connected socket descriptor (must be >= 0).

Returns: New ORM handle, or NULL on invalid descriptor or allocation failure.

Definition at line 145 of file orm.c.

References cap, and CWIST_ORM_SQLITE.

◆ cwist_orm_query()

cwist_error_t cwist_orm_query	(	cwist_orm_t *	orm,
		const char *	sql,
		cJSON **	result
	)

Execute a SELECT query and return the result set.

The returned cJSON object is an array. Each element is an object whose keys are column names and whose values are the row data. Values keep the legacy text-based typing (canonical integer text becomes a number); use cwist_orm_query_typed() for values typed by the column's SQLite storage class.

Parameters

orm	ORM session.
sql	Null-terminated SELECT statement.
result	[out] Pointer to a cJSON pointer. On success it receives a cJSON array that the caller must free with cJSON_Delete(). On failure the pointer is set to `NULL`.

Returns: cwist_error_t with err_i16 == 0 on success.

Execute a SELECT query and return the result set.

On success *result receives a cJSON array of row objects (empty array if no rows) that the caller must release with cJSON_Delete().

Parameters

orm	Active session.
sql	Null-terminated SQL query.
result	[out] Receives the rows array.

Returns: CWIST_SUCCESS on success; CWIST_ERROR_INVALID_PARAM for NULL arguments, CWIST_ERROR_IO on transport failure, or CWIST_ERROR_PROTOCOL on backend error or malformed response.

Definition at line 291 of file orm.c.

References cap, CWIST_ERR_INT16, CWIST_ERROR_INVALID_PARAM, CWIST_ERROR_IO, CWIST_ERROR_PROTOCOL, CWIST_SUCCESS, and make_error().

Referenced by cwist_orm_insert_returning_json(), cwist_orm_select(), and cwist_orm_select_one_json().

◆ cwist_orm_query_typed()

cwist_error_t cwist_orm_query_typed	(	cwist_orm_t *	orm,
		const char *	sql,
		cwist_orm_result_t **	result
	)

Execute a SELECT-style query and return column-typed rows.

Values are typed by each cell's SQLite storage class, not by its text, unlike cwist_orm_query() whose JSON values keep the legacy text-based typing (canonical integer text becomes a number there). Here a TEXT cell stays TEXT even when it holds digits, INTEGER keeps every digit above 2^53, and SQL NULL is a distinct type from an empty TEXT value.

Parameters

orm	ORM session.
sql	Null-terminated SELECT statement.
result	[out] Receives a heap-allocated cwist_orm_result_t that the caller must release with cwist_orm_result_free(). On failure the pointer is set to `NULL`.

Returns: cwist_error_t with err_i16 == 0 on success; CWIST_ERROR_INVALID_PARAM for NULL arguments, CWIST_ERROR_IO on transport failure, CWIST_ERROR_PROTOCOL on a backend error or a response without typed column metadata.

Reads the worker's "typed" payload, which types every cell from its SQLite storage class: INTEGER as exact int64 digits, REAL as a double, TEXT as a string, BLOB as decoded bytes with its length, and NULL as a distinct type. On success *result receives a heap-allocated result set the caller releases with cwist_orm_result_free().

Parameters

orm	Active session.
sql	Null-terminated SQL query.
result	[out] Receives the result set, or NULL on failure.

Returns: CWIST_SUCCESS on success; CWIST_ERROR_INVALID_PARAM for NULL arguments, CWIST_ERROR_IO on transport failure, or CWIST_ERROR_PROTOCOL on a backend error or a malformed typed payload.

Definition at line 1564 of file orm.c.

References cap, cwist_orm_result::cells, cwist_orm_result::column_count, cwist_orm_result::columns, CWIST_ERR_INT16, CWIST_ERROR_INVALID_PARAM, CWIST_ERROR_IO, CWIST_ERROR_NOMEM, CWIST_ERROR_PROTOCOL, cwist_orm_result_free(), CWIST_SUCCESS, make_error(), and cwist_orm_result::row_count.

◆ cwist_orm_result_cell()

const cwist_orm_value_t * cwist_orm_result_cell	(	const cwist_orm_result_t *	result,
		size_t	row,
		size_t	column
	)

Read one cell of a typed result set.

Parameters

result	Result set.
row	Row index.
column	Column index.

Returns: Pointer to the cell, or NULL when the coordinates are out of range or result is NULL. The pointer is owned by the result set and stays valid until cwist_orm_result_free().

Definition at line 1688 of file orm.c.

References cap, cwist_orm_result::cells, cwist_orm_result::column_count, and cwist_orm_result::row_count.

◆ cwist_orm_result_column_index()

size_t cwist_orm_result_column_index	(	const cwist_orm_result_t *	result,
		const char *	column
	)

Find a column index by name in a typed result set.

Parameters

result	Result set.
column	Column name.

Returns: The column index, or result->column_count when the name is not present (or either argument is NULL).

Definition at line 1680 of file orm.c.

References cap, cwist_orm_result::column_count, and cwist_orm_result::columns.

◆ cwist_orm_result_free()

void cwist_orm_result_free ( cwist_orm_result_t * result )

Release a result set from cwist_orm_query_typed().

Safe to call with NULL.

Parameters

result Result set to free.

Frees the column names, every owned cell payload, and the structure itself. Safe to call with NULL.

Parameters

result Result set to free.

Definition at line 1663 of file orm.c.

References cwist_orm_value::blob, cap, cwist_orm_result::cells, cwist_orm_result::column_count, cwist_orm_result::columns, cwist_orm_result::row_count, and cwist_orm_value::text.

Referenced by cwist_orm_query_typed().

◆ cwist_orm_rollback()

cwist_error_t cwist_orm_rollback ( cwist_orm_t * orm )

Roll back the current transaction.

Has no effect when immediate commit is enabled.

Parameters

orm	Active ORM session.

Returns: cwist_error_t with err_i16 == 0 on success, or CWIST_ERROR_IO on socket failure.

Parameters

orm	Active session.

Returns: CWIST_SUCCESS on success, otherwise an error code.

Definition at line 221 of file orm.c.

References cap, and cwist_orm_exec().

◆ cwist_orm_select()

cwist_error_t cwist_orm_select	(	cwist_orm_t *	orm,
		const char *	table,
		const char *	columns,
		const char *	where_clause,
		cJSON **	result
	)

Convenience SELECT helper.

Builds SELECT columns FROM table [WHERE where_clause] and returns the parsed result set.

Parameters

orm	ORM session.
table	Target table name.
columns	Comma-separated column list or `"*"`.
where_clause	Optional predicate without `WHERE`, or `NULL`.
result	[out] cJSON array result; caller must free.

Returns: cwist_error_t with err_i16 == 0 on success.

Convenience SELECT helper.

Parameters

orm	Active session.
table	Table name.
columns	Raw comma-separated column list (not escaped).
where_clause	Optional raw SQL WHERE condition (not escaped).
result	[out] Receives a cJSON array of row objects; caller must release with cJSON_Delete().

Returns: CWIST_SUCCESS on success; CWIST_ERROR_INVALID_PARAM for NULL arguments, CWIST_ERROR_NOMEM on allocation failure, otherwise the error from cwist_orm_query().

Definition at line 773 of file orm.c.

References cap, CWIST_ERR_INT16, CWIST_ERROR_INVALID_PARAM, CWIST_ERROR_NOMEM, cwist_orm_query(), and make_error().

◆ cwist_orm_select_one_double()

cwist_error_t cwist_orm_select_one_double	(	cwist_orm_t *	orm,
		const char *	table,
		const char *	column,
		const char *	where_clause,
		double *	out
	)

Select a single column value from the first matching row as a double.

Parameters

orm	Active session.
table	Table name.
column	Column name.
where_clause	Optional raw SQL WHERE condition (not escaped).
out	[out] Receives the value as a double.

Returns: CWIST_SUCCESS on success; otherwise the error from cwist_orm_select_one_json() or CWIST_ERROR_PROTOCOL when the returned value is not a number.

Definition at line 1190 of file orm.c.

References cap, CWIST_ERROR_PROTOCOL, and cwist_orm_select_one_json().

◆ cwist_orm_select_one_i64()

cwist_error_t cwist_orm_select_one_i64	(	cwist_orm_t *	orm,
		const char *	table,
		const char *	column,
		const char *	where_clause,
		int64_t *	out
	)

Select a single integer cell exactly as an int64_t.

Same query as cwist_orm_select_one_llong(), but the value is read from the integer digits the worker sent instead of through a cJSON number (a double), so integers above 2^53 (snowflake-style IDs) keep every digit. The cell must be a JSON integer, or a JSON string holding canonical integer text (an optional '-' and digits, no leading zeros).

Parameters

orm	Active session.
table	Table name.
column	Column name.
where_clause	Optional raw SQL WHERE condition (not escaped).
out	[out] Receives the value.

Returns: CWIST_SUCCESS on success; CWIST_ERROR_INVALID_PARAM for NULL arguments; CWIST_ERROR_IO when the worker exchange fails; CWIST_ERROR_PROTOCOL when no row is returned, or the value is not an integer or does not fit in int64_t. out is unchanged on failure.

Definition at line 1387 of file orm.c.

References cap, CWIST_ERR_INT16, CWIST_ERROR_INVALID_PARAM, CWIST_ERROR_NOMEM, and make_error().

◆ cwist_orm_select_one_int()

cwist_error_t cwist_orm_select_one_int	(	cwist_orm_t *	orm,
		const char *	table,
		const char *	column,
		const char *	where_clause,
		int *	out
	)

Select a single column value from the first matching row as an int.

Parameters

orm	Active session.
table	Table name.
column	Column name.
where_clause	Optional raw SQL WHERE condition (not escaped).
out	[out] Receives the value as an int.

Returns: CWIST_SUCCESS on success; otherwise the error from cwist_orm_select_one_json() or CWIST_ERROR_PROTOCOL when the returned value is not a number.

Definition at line 1112 of file orm.c.

References cap, CWIST_ERROR_PROTOCOL, and cwist_orm_select_one_json().

◆ cwist_orm_select_one_json()

cwist_error_t cwist_orm_select_one_json	(	cwist_orm_t *	orm,
		const char *	table,
		const char *	column,
		const char *	where_clause,
		cJSON **	out
	)

Select a single column value from the first matching row as JSON.

Runs a SELECT column FROM table [WHERE ...] LIMIT 1 query and duplicates the column value from the first result row.

Parameters

orm	Active session.
table	Table name.
column	Column name.
where_clause	Optional raw SQL WHERE condition (not escaped).
out	[out] Receives a duplicated cJSON value; caller must release with cJSON_Delete().

Returns: CWIST_SUCCESS on success; CWIST_ERROR_INVALID_PARAM for NULL arguments, CWIST_ERROR_NOMEM on allocation failure, CWIST_ERROR_PROTOCOL when no row or column value is returned.

Definition at line 1053 of file orm.c.

References cap, CWIST_ERR_INT16, CWIST_ERROR_INVALID_PARAM, CWIST_ERROR_NOMEM, CWIST_ERROR_PROTOCOL, cwist_orm_query(), and make_error().

Referenced by cwist_orm_select_one_double(), cwist_orm_select_one_int(), cwist_orm_select_one_llong(), cwist_orm_select_one_long(), and cwist_orm_select_one_string().

◆ cwist_orm_select_one_llong()

cwist_error_t cwist_orm_select_one_llong	(	cwist_orm_t *	orm,
		const char *	table,
		const char *	column,
		const char *	where_clause,
		long long *	out
	)

Select a single column value from the first matching row as a long long.

Parameters

orm	Active session.
table	Table name.
column	Column name.
where_clause	Optional raw SQL WHERE condition (not escaped).
out	[out] Receives the value as a long long.

Returns: CWIST_SUCCESS on success; otherwise the error from cwist_orm_select_one_json() or CWIST_ERROR_PROTOCOL when the returned value is not a number.

Definition at line 1164 of file orm.c.

References cap, CWIST_ERROR_PROTOCOL, and cwist_orm_select_one_json().

◆ cwist_orm_select_one_long()

cwist_error_t cwist_orm_select_one_long	(	cwist_orm_t *	orm,
		const char *	table,
		const char *	column,
		const char *	where_clause,
		long *	out
	)

Select a single column value from the first matching row as a long.

Parameters

orm	Active session.
table	Table name.
column	Column name.
where_clause	Optional raw SQL WHERE condition (not escaped).
out	[out] Receives the value as a long.

Returns: CWIST_SUCCESS on success; otherwise the error from cwist_orm_select_one_json() or CWIST_ERROR_PROTOCOL when the returned value is not a number.

Definition at line 1138 of file orm.c.

References cap, CWIST_ERROR_PROTOCOL, and cwist_orm_select_one_json().

◆ cwist_orm_select_one_string()

cwist_error_t cwist_orm_select_one_string	(	cwist_orm_t *	orm,
		const char *	table,
		const char *	column,
		const char *	where_clause,
		char **	out
	)

Select a single column value from the first matching row as a string.

Parameters

orm	Active session.
table	Table name.
column	Column name.
where_clause	Optional raw SQL WHERE condition (not escaped).
out	[out] Receives a heap-allocated copy of the string; caller must release with free().

Returns: CWIST_SUCCESS on success; otherwise the error from cwist_orm_select_one_json(), CWIST_ERROR_PROTOCOL when the returned value is not a string, or CWIST_ERROR_NOMEM when the string copy cannot be allocated.

Definition at line 1218 of file orm.c.

References cap, CWIST_ERROR_NOMEM, CWIST_ERROR_PROTOCOL, and cwist_orm_select_one_json().

◆ cwist_orm_update()

cwist_error_t cwist_orm_update	(	cwist_orm_t *	orm,
		const char *	table,
		const cJSON *	data,
		const char *	where_clause
	)

Update rows in a table.

Builds an UPDATE statement from the key-value pairs in data. If where_clause is non-NULL it is appended as the WHERE clause.

Parameters

orm	ORM session.
table	Target table name.
data	cJSON object with columns to update.
where_clause	Optional SQL predicate (without the leading `WHERE` keyword), or `NULL` to update all rows.

Returns: cwist_error_t with err_i16 == 0 on success.

Update rows in a table.

Builds UPDATE table SET key=value,... from the object's entries; an empty object is rejected. If where_clause is non-empty it is appended as a WHERE clause (a NULL or empty clause updates all rows).

Parameters

orm	Active session.
table	Table name.
data	JSON object with column names as keys (must be non-empty).
where_clause	Optional raw SQL WHERE condition (not escaped).

Returns: CWIST_SUCCESS on success; CWIST_ERROR_INVALID_PARAM for NULL arguments or an empty object, CWIST_ERROR_NOMEM on allocation failure, otherwise the error from cwist_orm_exec().

Definition at line 629 of file orm.c.

References cap, CWIST_ERR_INT16, CWIST_ERROR_INVALID_PARAM, CWIST_ERROR_NOMEM, cwist_orm_exec(), and make_error().

◆ cwist_orm_use_dialect()

void cwist_orm_use_dialect	(	cwist_orm_t *	orm,
		cwist_orm_dialect_t	dialect
	)

Select the SQL dialect used for query generation.

The dialect affects identifier quoting, boolean literals, and dialect-specific syntax in high-level helpers such as cwist_orm_insert() and cwist_orm_update().

Parameters

orm	ORM session.
dialect	Target dialect. Default is CWIST_ORM_SQLITE.

Affects identifier quoting and dialect-specific statements generated by the high-level helpers. Does nothing if orm is NULL.

Parameters

orm	Session to configure.
dialect	Dialect to use (e.g. CWIST_ORM_SQLITE).

Definition at line 201 of file orm.c.

References cap.

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ cwist_orm_insert_r

◆ cwist_orm_select_one

Typedef Documentation

◆ cwist_orm_dialect_t

◆ cwist_orm_result_t

◆ cwist_orm_t

◆ cwist_orm_value_t

◆ cwist_orm_value_type_t

Enumeration Type Documentation

◆ cwist_orm_dialect

◆ cwist_orm_value_type

Function Documentation

◆ cwist_orm_close_socket()

◆ cwist_orm_commit()

◆ cwist_orm_delete()

◆ cwist_orm_exec()

◆ cwist_orm_immediate_commit()

◆ cwist_orm_insert()

◆ cwist_orm_insert_returning_i64()

◆ cwist_orm_insert_returning_int()

◆ cwist_orm_insert_returning_json()

◆ cwist_orm_insert_returning_llong()

◆ cwist_orm_insert_returning_long()

◆ cwist_orm_open_socket()

◆ cwist_orm_query()

◆ cwist_orm_query_typed()

◆ cwist_orm_result_cell()

◆ cwist_orm_result_column_index()

◆ cwist_orm_result_free()

◆ cwist_orm_rollback()

◆ cwist_orm_select()

◆ cwist_orm_select_one_double()

◆ cwist_orm_select_one_i64()

◆ cwist_orm_select_one_int()

◆ cwist_orm_select_one_json()

◆ cwist_orm_select_one_llong()

◆ cwist_orm_select_one_long()

◆ cwist_orm_select_one_string()

◆ cwist_orm_update()

◆ cwist_orm_use_dialect()