1. Getting Started

1.1 Minimal Example

#include <cognica/cognica.h>
#include <stdio.h>

int main(void) {
  cognica_database db = NULL;
  cognica_connection conn = NULL;
  cognica_result result = NULL;

  cognica_open("/tmp/mydb", &db);
  cognica_connect(db, &conn);

  cognica_execute(conn, "CREATE TABLE t (id INT64 PRIMARY KEY, name VARCHAR)", &result);
  cognica_result_destroy(result);

  cognica_execute(conn, "INSERT INTO t VALUES (1, 'Alice')", &result);
  cognica_result_destroy(result);

  cognica_execute(conn, "SELECT id, name FROM t", &result);
  for (int64_t r = 0; r < cognica_result_row_count(result); ++r) {
    int64_t len = 0;
    printf("id=%lld name=%.*s\n",
           (long long)cognica_result_get_int64(result, r, 0),
           (int)len, cognica_result_get_varchar(result, r, 1, &len));
  }
  cognica_result_destroy(result);

  cognica_disconnect(conn);
  cognica_close(db);
  return 0;
}

Build: cc -o example example.c -lcognica-database

1.2 Handle Ownership Model

All resources follow a strict parent-child hierarchy. A parent handle refuses to close while any child handle is still alive, returning COGNICA_ERROR_MISUSE. Resources must be destroyed in reverse order of creation.

cognica_database
  +-- cognica_connection
        +-- cognica_result
        +-- cognica_prepared
        +-- cognica_cursor
        +-- cognica_appender

Multiple cognica_database handles may coexist in a single process. Each owns an independent engine instance with no shared global state.

1.3 Error Handling Convention

Every function that can fail returns cognica_status. On failure, a human-readable error message is available from the nearest handle:

• Database-level errors: cognica_database_errmsg(db)
• Connection-level errors: cognica_connection_errmsg(conn)

The returned string pointer is valid until the next operation on the same handle. Callers should copy the string if it needs to outlive that window.

1.4 Thread Safety

A cognica_database handle is safe to share across threads. A cognica_connection handle is not: the caller must serialize all access to a given connection. The recommended pattern is one connection per thread.

---