nuke_db.h File Reference

High-Performance Read-Optimal Persistent Store using SQLite. More...

#include <sqlite3.h>
#include <stdbool.h>

Include dependency graph for nuke_db.h:

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

Go to the source code of this file.

Classes
struct	cwist_nuke_db_t
	Nuke DB Context. More...

Macros
#define	CWIST_NUKE_OK   0
	Return codes for cwist_nuke_init.
#define	CWIST_NUKE_ERR_GENERIC   (-1)
#define	CWIST_NUKE_ERR_LOW_MEMORY   (-2)

Typedefs
typedef struct cwist_nuke_db_t	cwist_nuke_db_t
	Nuke DB Context.

Functions
int	cwist_nuke_init (const char *disk_path, int sync_interval_ms)
	Initialize Nuke DB.
int	cwist_nuke_sync (void)
	Force synchronization from Memory to Disk.
void	cwist_nuke_close (void)
	Close databases safely. Performs a final synchronization before closing handles.
sqlite3 *	cwist_nuke_get_db (void)
	Get the raw SQLite3 handle for the In-Memory DB.
void	cwist_nuke_signal_handler (int signum)
	Internal signal handler. Typically set up by cwist_nuke_init.
unsigned char *	cwist_nuke_serialize (sqlite3_int64 *out_size)
	Serialize the in-memory database to a raw byte buffer.
int	cwist_nuke_deserialize (unsigned char *data, sqlite3_int64 data_len)
	Load a raw SQLite byte buffer into the in-memory database.

Detailed Description

High-Performance Read-Optimal Persistent Store using SQLite.

Concept:

• Reads: Always from In-Memory DB (Extreme speed).
• Writes: Immediately synchronized to Disk DB via WAL (Durability).
• Trade-off: Slightly higher write latency for the sake of guaranteed durability and non-blocking ultra-fast reads.

Definition in file nuke_db.h.

Macro Definition Documentation

CWIST_NUKE_ERR_GENERIC

#define CWIST_NUKE_ERR_GENERIC   (-1)

Definition at line 22 of file nuke_db.h.

CWIST_NUKE_ERR_LOW_MEMORY

#define CWIST_NUKE_ERR_LOW_MEMORY   (-2)

Definition at line 23 of file nuke_db.h.

CWIST_NUKE_OK

#define CWIST_NUKE_OK   0

Return codes for cwist_nuke_init.

Definition at line 21 of file nuke_db.h.

Typedef Documentation

cwist_nuke_db_t

typedef struct cwist_nuke_db_t cwist_nuke_db_t

Nuke DB Context.

Logic:

1. Init: Load disk DB into Memory DB. Enables WAL mode on disk.
2. Runtime:
   • SELECTs happen in Memory.
   • INSERT/UPDATE/DELETE trigger immediate background sync to Disk on COMMIT.
3. Periodic: Background thread also performs periodic sync as a fail-safe.
4. Exit: Catch signals (SIGINT, SIGTERM) and force final Sync.

Function Documentation

cwist_nuke_close()

void cwist_nuke_close

(

void

)

Close databases safely. Performs a final synchronization before closing handles.

Close databases safely. Performs a final synchronization before closing handles.

Definition at line 293 of file nuke_db.c.

References cwist_nuke_sync().

Referenced by cwist_app_destroy(), cwist_app_use_nuke_db(), and cwist_nuke_init().

cwist_nuke_deserialize()

int cwist_nuke_deserialize	(	unsigned char *	data,
		sqlite3_int64	data_len
	)

Load a raw SQLite byte buffer into the in-memory database.

Uses sqlite3_deserialize() to replace the current in-memory database content with the provided bytes. Ownership of data is transferred to SQLite (allocated with sqlite3_malloc()); do not free it yourself after a successful call.

Parameters

data	Buffer previously obtained via cwist_nuke_serialize() or cwist_db_sync_pull(). Must be sqlite3_malloc()-allocated.
data_len	Length of data in bytes.

Returns

0 on success, -1 on failure.

Load a raw SQLite byte buffer into the in-memory database.

Parameters

data	Serialized database buffer; ownership transfers to SQLite, which frees it on close (SQLITE_DESERIALIZE_FREEONCLOSE).
data_len	Length of data in bytes.

Returns

0 on success, or -1 on invalid arguments or when running in disk mode.

Definition at line 520 of file nuke_db.c.

References cwist_nuke_db_t::is_disk_mode, and cwist_nuke_db_t::mem_db.

cwist_nuke_get_db()

sqlite3 * cwist_nuke_get_db

(

void

)

Get the raw SQLite3 handle for the In-Memory DB.

Returns

Pointer to the active sqlite3* handle. Returns the disk handle when NukeDB is operating in disk-only fallback mode.

Get the raw SQLite3 handle for the In-Memory DB.

Returns

The in-memory handle in normal mode, or the disk handle after a low-memory fallback to disk mode. May be NULL before init or after close.

Definition at line 478 of file nuke_db.c.

References cwist_nuke_db_t::disk_db, cwist_nuke_db_t::is_disk_mode, and cwist_nuke_db_t::mem_db.

Referenced by cwist_app_get_db(), and cwist_app_use_nuke_db().

cwist_nuke_init()

int cwist_nuke_init	(	const char *	disk_path,
		int	sync_interval_ms
	)

Initialize Nuke DB.

Loads the disk database into memory (if it exists). Sets up signal handlers for safe exit (SIGINT, SIGTERM). Starts a background thread for auto-sync if interval > 0.

Parameters

disk_path	Path to the persistent database file.
sync_interval_ms	Auto-sync interval in ms (0 to disable).

Returns

0 on success, negative on failure (see CWIST_NUKE_ERR_* codes).

Initialize Nuke DB.

Parameters

disk_path	Path to the on-disk SQLite database.
sync_interval_ms	Background sync interval in milliseconds.

Returns

NUKE status code describing success, low-memory fallback, or failure.

Definition at line 377 of file nuke_db.c.

References cwist_nuke_db_t::auto_sync, cwist_get_available_ram(), cwist_nuke_close(), CWIST_NUKE_ERR_GENERIC, CWIST_NUKE_ERR_LOW_MEMORY, CWIST_NUKE_OK, cwist_strdup(), cwist_nuke_db_t::disk_db, cwist_nuke_db_t::disk_path, cwist_nuke_db_t::is_disk_mode, cwist_nuke_db_t::load_successful, cwist_nuke_db_t::mem_db, and cwist_nuke_db_t::sync_interval_ms.

Referenced by cwist_app_use_nuke_db().

cwist_nuke_serialize()

unsigned char * cwist_nuke_serialize

(

sqlite3_int64 *

out_size

)

Serialize the in-memory database to a raw byte buffer.

Uses sqlite3_serialize() for direct byte-level access to the SQLite image, which avoids the overhead of the backup API and enables encryption or network transfer without a temporary file.

The returned buffer is allocated by sqlite3_malloc() and must be freed with sqlite3_free(). Returns NULL on failure or when NukeDB is not initialised.

Parameters

[out]

out_size

Set to the number of bytes in the returned buffer.

Returns

sqlite3_malloc()-allocated byte buffer, or NULL on failure.

Serialize the in-memory database to a raw byte buffer.

Parameters

out_size

Receives the serialized byte count.

Returns

Heap buffer produced by sqlite3_serialize (caller frees with sqlite3_free), or NULL when out_size is NULL or no database is open. Thread-safe via g_nuke_lock.

Definition at line 497 of file nuke_db.c.

References cwist_nuke_db_t::disk_db, cwist_nuke_db_t::is_disk_mode, and cwist_nuke_db_t::mem_db.

cwist_nuke_signal_handler()

void cwist_nuke_signal_handler

(

int

signum

)

Internal signal handler. Typically set up by cwist_nuke_init.

Internal signal handler. Typically set up by cwist_nuke_init.

Parameters

signum

Signal number; unused.

Definition at line 487 of file nuke_db.c.

References CWIST_UNUSED.

cwist_nuke_sync()

int cwist_nuke_sync

(

void

)

Force synchronization from Memory to Disk.

Returns

0 on success, -1 on failure.

Force synchronization from Memory to Disk.

Returns

0 on success, or -1 when syncing is impossible or fails.

Definition at line 228 of file nuke_db.c.

References cwist_nuke_db_t::disk_db, cwist_nuke_db_t::is_disk_mode, cwist_nuke_db_t::load_successful, and cwist_nuke_db_t::mem_db.

Referenced by cwist_nuke_close().