db.c File Reference

SQLite convenience wrappers plus lightweight heuristics for query execution and JSON healing. More...

#include <cwist/core/db/sql.h>
#include <cwist/core/utils/json_heal.h>
#include <cwist/core/utils/zod.h>
#include <cwist/sys/err/cwist_err.h>
#include <cwist/core/mem/alloc.h>
#include <sqlite3.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>
#include <stdbool.h>

Include dependency graph for db.c:

Go to the source code of this file.

Functions
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)
	Heal, validate, and insert a JSON object into a table.
cwist_error_t	cwist_db_query_strict (cwist_db *db, const char *sql, cJSON **result, const cwist_schema_t *schema)
	Execute a query and require the result rows to satisfy a CWIST schema.

Detailed Description

SQLite convenience wrappers plus lightweight heuristics for query execution and JSON healing.

Definition in file db.c.

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.

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_insert_healed(), and 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
	)

Heal, validate, and insert a JSON object into a table.

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).

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.

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"}].

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(), and cwist_db_query_strict().

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 query and require the result rows to satisfy a CWIST schema.

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.

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().