sql.h File Reference

Database operations wrapper (SQLite3). More...

#include <sqlite3.h>
#include <stddef.h>
#include <cwist/sys/err/cwist_err.h>
#include <cjson/cJSON.h>
#include <cwist/core/utils/json_heal.h>
#include <cwist/core/utils/zod.h>

Include dependency graph for sql.h:

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

Go to the source code of this file.

Classes
struct	cwist_db
	Wrapper for Database Operations. Currently uses SQLite3. More...

Typedefs
typedef struct cwist_db	cwist_db
	Wrapper for Database Operations. Currently uses SQLite3.

Functions
API
cwist_error_t	cwist_db_open (cwist_db **db, const char *path)
	Open a SQLite database and wrap the resulting connection in a CWIST handle.
cwist_error_t	cwist_db_open_memory (cwist_db **db, const void *buf, size_t len, int readonly)
	Open a CWIST database from an in-memory SQLite image.
cwist_error_t	cwist_db_serialize (cwist_db *db, void **out, size_t *out_len)
	Serialize a CWIST database into a freshly allocated image buffer.
void	cwist_db_close (cwist_db *db)
	Close a CWIST database wrapper and its underlying SQLite connection.
cwist_error_t	cwist_db_exec (cwist_db *db, const char *sql)
	Execute an arbitrary SQL statement string without returning rows.
cwist_error_t	cwist_db_query (cwist_db *db, const char *sql, cJSON **result)
	Execute a SQL query and collect every row into a cJSON array.
cwist_error_t	cwist_db_insert_healed (cwist_db *db, const char *table, const char *json_str, const cwist_schema_t *schema, const cwist_heal_config_t *heal_cfg)
	Insert a (possibly broken) JSON object into a table with self-healing.
cwist_error_t	cwist_db_query_strict (cwist_db *db, const char *sql, cJSON **result, const cwist_schema_t *schema)
	Execute a SELECT query and strictly validate each result row.

Detailed Description

Database operations wrapper (SQLite3).

Definition in file sql.h.

Typedef Documentation

cwist_db

typedef struct cwist_db cwist_db

Wrapper for Database Operations. Currently uses SQLite3.

Function Documentation

cwist_db_close()

void cwist_db_close

(

cwist_db *

db

)

Close a CWIST database wrapper and its underlying SQLite connection.

Close database connection.

Parameters

db	Database wrapper to close.

Definition at line 295 of file db.c.

References cwist_db::conn, and cwist_free().

Referenced by cwist_app_destroy(), cwist_app_use_db(), cwist_app_use_nuke_db(), cwist_db_pool_create(), and cwist_db_pool_destroy_timeout().

cwist_db_exec()

cwist_error_t cwist_db_exec	(	cwist_db *	db,
		const char *	sql
	)

Execute an arbitrary SQL statement string without returning rows.

Execute a command (INSERT, UPDATE, DELETE, CREATE). Does not return rows. Returns err_i16 = -1 when db/sql pointer is invalid.

Parameters

db	Open database wrapper.
sql	SQL text to execute.

Returns

Tagged CWIST error describing success or failure.

Definition at line 312 of file db.c.

References cwist_db::conn, CWIST_ERR_INT16, __prim_cwist_error_t::err_i16, cwist_error_t::error, and make_error().

Referenced by cwist_db_pool_exec().

cwist_db_insert_healed()

cwist_error_t cwist_db_insert_healed	(	cwist_db *	db,
		const char *	table,
		const char *	json_str,
		const cwist_schema_t *	schema,
		const cwist_heal_config_t *	heal_cfg
	)

Insert a (possibly broken) JSON object into a table with self-healing.

Applies the self-healing layer to json_str, validates the result with the Zod-like strict validator (if a schema is provided), then generates and executes an INSERT SQL statement.

Returns an error when:

• the JSON cannot be healed to a confidence >= cfg->threshold
• Zod validation rejects the healed object (missing required fields / wrong types)
• the SQL execution fails

Parameters

db	Open database handle.
table	Target table name (used verbatim in the SQL).
json_str	Raw (possibly malformed) JSON string.
schema	Schema used for L2 healing and strict validation (may be NULL).
heal_cfg	Healing configuration (may be NULL for defaults).

Returns

cwist_error_t; err_i16 == 0 on success.

Insert a (possibly broken) JSON object into a table with self-healing.

Parameters

db	Open database wrapper.
table	Destination table name.
json_str	Raw JSON input to heal and insert.
schema	Optional schema used for alignment and validation.
heal_cfg	Optional healing configuration overrides.

Returns

Tagged CWIST error describing success or failure.

Definition at line 504 of file db.c.

References cwist_db_exec(), CWIST_ERR_INT16, cwist_heal_result_free(), cwist_json_heal(), cwist_zod_parse(), cwist_zod_print_errors(), __prim_cwist_error_t::err_i16, cwist_error_t::error, cwist_heal_result::json, make_error(), cwist_heal_config::schema, cwist_heal_config::threshold, and cwist_zod_result::valid.

cwist_db_open()

cwist_error_t cwist_db_open	(	cwist_db **	db,
		const char *	path
	)

Open a SQLite database and wrap the resulting connection in a CWIST handle.

Connect to a database (or open file). path: Path to SQLite file (or ":memory:")

Parameters

db	Output pointer receiving the allocated database wrapper.
path	Filesystem path or SQLite URI to open.

Returns

Tagged CWIST error describing success or failure.

Definition at line 154 of file db.c.

References cwist_alloc(), CWIST_ERR_INT16, cwist_free(), __prim_cwist_error_t::err_i16, cwist_error_t::error, and make_error().

Referenced by cwist_app_use_db(), and cwist_db_pool_create().

cwist_db_open_memory()

cwist_error_t cwist_db_open_memory	(	cwist_db **	db,
		const void *	buf,
		size_t	len,
		int	readonly
	)

Open a CWIST database from an in-memory SQLite image.

Open a database from an in-memory SQLite image (blob), e.g. one fetched by a WASM/edge host instead of a filesystem path. The image is copied with sqlite3_malloc64(), so the caller keeps ownership of buf.

Parameters

db	Receives the handle (NULL on failure).
buf	Serialized SQLite database image.
len	Image length in bytes.
readonly	Non-zero opens the image read-only (writes fail with SQLITE_READONLY); zero allows the in-memory db to grow.

The image is copied into SQLite-owned memory (SQLITE_DESERIALIZE_FREEONCLOSE), so the caller keeps ownership of buf. Same connection defaults as cwist_db_open(): FULLMUTEX, no extra pragmas.

Parameters

db	Receives the handle (NULL on failure).
buf	Serialized SQLite database image.
len	Image length in bytes.
readonly	Non-zero opens the image read-only; zero allows growth.

Returns

Tagged CWIST error describing success or failure.

Definition at line 198 of file db.c.

References cwist_alloc(), CWIST_ERR_INT16, cwist_free(), __prim_cwist_error_t::err_i16, cwist_error_t::error, and make_error().

cwist_db_query()

cwist_error_t cwist_db_query	(	cwist_db *	db,
		const char *	sql,
		cJSON **	result
	)

Execute a SQL query and collect every row into a cJSON array.

Execute a query and return results as a cJSON Array of Objects. Example: [{"id":1, "name":"foo"}, {"id":2, "name":"bar"}] The result pointer is reset to NULL on entry and left NULL on failure.

Parameters

db	Open database wrapper.
sql	SQL text to execute.
result	Output pointer receiving the cJSON row array.

Returns

Tagged CWIST error describing success or failure.

Definition at line 374 of file db.c.

References cwist_db::conn, CWIST_ERR_INT16, __prim_cwist_error_t::err_i16, cwist_error_t::error, and make_error().

Referenced by cwist_db_pool_query().

cwist_db_query_strict()

cwist_error_t cwist_db_query_strict	(	cwist_db *	db,
		const char *	sql,
		cJSON **	result,
		const cwist_schema_t *	schema
	)

Execute a SELECT query and strictly validate each result row.

Rows that fail Zod validation are excluded from the returned array. When schema is NULL the function behaves identically to cwist_db_query().

Parameters

db	Open database handle.
sql	SQL SELECT statement.
result	[out] cJSON array containing only conforming rows.
schema	Schema to validate each row against (may be NULL).

Returns

cwist_error_t; err_i16 == 0 on success.

Execute a SELECT query and strictly validate each result row.

Parameters

db	Open database wrapper.
sql	SQL text to execute.
result	Output pointer receiving the cJSON row array on success.
schema	Schema applied to every returned row.

Returns

Tagged CWIST error describing success or validation failure.

Definition at line 574 of file db.c.

References cwist_db_query(), CWIST_ERR_INT16, CWIST_ERR_JSON, cwist_zod_validate(), __prim_cwist_error_t::err_i16, cwist_error_t::error, cwist_error_t::errtype, make_error(), and cwist_zod_result::valid.

cwist_db_serialize()

cwist_error_t cwist_db_serialize	(	cwist_db *	db,
		void **	out,
		size_t *	out_len
	)

Serialize a CWIST database into a freshly allocated image buffer.

Serialize the database image into a freshly allocated buffer, suitable for persisting back to a blob or handing to cwist_db_open_memory(). Caller frees out with cwist_free().

Parameters

db	Open database wrapper.
out	Receives the image (free with cwist_free()).
out_len	Receives the image length in bytes.

Returns

Tagged CWIST error describing success or failure.

Definition at line 257 of file db.c.

References cwist_db::conn, cwist_alloc(), CWIST_ERR_INT16, __prim_cwist_error_t::err_i16, cwist_error_t::error, and make_error().