C SDK

Minimal C client library for ParticleDB. Communicates over the REST API (POST /v1/sql) using libcurl for HTTP. JSON responses are parsed with a hand-rolled parser — no external JSON library required.

Prerequisites

A C11 compiler (gcc, clang, etc.)
libcurl development headers and library

# macOS -- libcurl ships with Xcode / CommandLineTools
# No extra packages needed

# Debian/Ubuntu
sudo apt-get install libcurl4-openssl-dev

# Fedora/RHEL
sudo dnf install libcurl-devel

Building

cd sdk/c

# Build static (libparticledb.a) and shared (libparticledb.so / .dylib)
make

# Build only the static library
make static

# Build the example program
make examples

# Install to /usr/local (or PREFIX=/opt/particledb make install)
sudo make install

Quick Start

#include <stdio.h>
#include "particledb.h"

int main(void) {
    pdb_client_t *client = pdb_connect("localhost", 8080, NULL, NULL, NULL);
    if (!client) return 1;

    pdb_execute(client, "CREATE TABLE demo (id BIGINT PRIMARY KEY, name TEXT)");
    pdb_execute(client, "INSERT INTO demo VALUES (1, 'Alice')");

    pdb_result_t *r = pdb_query(client, "SELECT id, name FROM demo");
    for (int i = 0; i < pdb_result_row_count(r); i++) {
        printf("id=%lld name=%s\n",
               (long long)pdb_result_get_int(r, i, 0),
               pdb_result_get_string(r, i, 1));
    }

    pdb_result_free(r);
    pdb_disconnect(client);
    return 0;
}

Compile and link:

cc -Iinclude -o demo demo.c -Lbuild -lparticledb -lcurl

API Reference

Connection

Function	Description
`pdb_connect(host, port, user, pass, db)`	Connect to ParticleDB REST API. Returns client handle or NULL.
`pdb_disconnect(client)`	Disconnect and free all resources. Safe to call with NULL.
`pdb_last_error(client)`	Last error message, or NULL if no error.

Query Execution

Function	Description
`pdb_query(client, sql)`	Execute a query returning rows. Caller must free with `pdb_result_free()`. Returns NULL on error.
`pdb_execute(client, sql)`	Execute a statement (INSERT, UPDATE, etc.). Returns affected row count (>= 0) or negative `PDB_ERR_*` code.

Result Inspection

Function	Description
`pdb_result_row_count(result)`	Number of rows in the result set.
`pdb_result_col_count(result)`	Number of columns in the result set.
`pdb_result_col_name(result, col)`	Column name by 0-based index.
`pdb_result_get_string(result, row, col)`	Cell value as string. Returns NULL for SQL NULL.
`pdb_result_get_int(result, row, col)`	Cell value as int64. Returns 0 for NULL.
`pdb_result_get_double(result, row, col)`	Cell value as double. Returns 0.0 for NULL.
`pdb_result_is_null(result, row, col)`	Non-zero if the cell is SQL NULL.
`pdb_result_free(result)`	Free a result set. Safe to call with NULL.

Error Codes

Constant	Value	Meaning
`PDB_OK`	0	Success
`PDB_ERR_CONNECT`	-1	Connection failed
`PDB_ERR_CURL`	-2	libcurl error
`PDB_ERR_HTTP`	-3	HTTP or server error
`PDB_ERR_PARSE`	-4	JSON parse failure
`PDB_ERR_NULL`	-5	NULL argument
`PDB_ERR_BOUNDS`	-6	Index out of bounds

Architecture

Application
    |
    v
particledb.h  (public API)
    |
    v
particledb.c  (HTTP + JSON parsing)
    |
    v
libcurl       (HTTP transport)
    |
    v
ParticleDB    (POST /v1/sql on port 8080)

Thread Safety

Each pdb_client_t handle contains its own libcurl easy handle and must be used from a single thread at a time. To use ParticleDB from multiple threads, create one client per thread.

Next Steps

SQL Reference — Full SQL syntax
C++ SDK — Header-only C++17 SDK with higher-level helpers
HTTP API — REST API reference