// calogDb.h -- calog database library.
//
// Registers a small set of inline natives that a script of any engine can call:
//   dbOpen(driver, conn) -> handle     (driver: "sqlite" / "postgres" / "mysql")
//   dbExec(handle, sql, ...params) -> rowsAffected
//   dbQuery(handle, sql, ...params) -> list of {column: value} row maps
//   dbClose(handle)
// Values marshal by CalogValueT: NULL <-> nil, integers/reals as-is, text and BLOBs as
// binary-safe strings. Parameters are always BOUND (never string-spliced), so scripts are
// injection-safe by construction. The natives are INLINE -- a slow query blocks only the
// calling script's context thread, not the host. Backends are compiled in with
// CALOG_WITH_SQLITE / _PG / _MYSQL.
//
// Ownership: a connection handle belongs to the context that opened it. Handles are NOT
// reference-counted, so it is undefined behaviour for two contexts to use the same handle
// concurrently, or for one context to close a handle while another is mid-operation on it
// (a use-after-free, exactly as with a raw file descriptor). Pass work between contexts,
// not live handles.
//
// Connection strings:
//   sqlite    -- a file path, or ":memory:".
//   postgres  -- a libpq conninfo, e.g. "host=/tmp dbname=app user=me". TLS follows libpq
//                (default sslmode=prefer: use TLS if offered, else plain, no verification).
//   mysql     -- "key=value ..." over host/user/password/dbname/port/socket, plus sslmode
//                (default "prefer": TLS if offered else plain, no verification; "disable" =
//                plain; "require" = TLS + server-certificate verification).

#ifndef CALOG_DB_H
#define CALOG_DB_H

#include "calog.h"

// Register the DB natives on a runtime. Idempotent across runtimes (they share a
// process-wide connection registry). Returns calogOkE or an error.
int32_t calogDbRegister(CalogT *calog);

// Close any still-open connections and free the process-wide DB registry. Call it AFTER
// the runtime is torn down (calogDestroy), since it invalidates the natives' state.
void    calogDbShutdown(void);

#endif