C ABI

The WorkaDB C API uses the wepg_ prefix and is designed to remain stable across versions. It exposes a minimal set of calls to initialize an engine, execute SQL, and shut down cleanly.

Type reference

wepg_handle

Opaque handle representing a single embedded engine instance.

wepg_status

Return status for all API calls.

Value	Meaning
WEPG_OK	Success.
WEPG_ERR_INVALID_CONFIG	Invalid input pointers or configuration.
WEPG_ERR_INITDB_FAILED	Template-based initdb failed.
WEPG_ERR_EXEC_FAILED	SQL execution failed.
WEPG_ERR_BUFFER_TOO_SMALL	Response buffer too small or max size exceeded.
WEPG_ERR_INCOMPATIBLE_PGDATA	PGDATA version mismatch.
WEPG_ERR_UPGRADE_REQUIRED	Upgrade needed for current PGDATA.
WEPG_ERR_UNSUPPORTED	Unsupported feature or mode.
WEPG_ERR_INTERNAL	Internal failure.

wepg_mode

Request mode for wepg_step.

• WEPG_MODE_SQL: Execute UTF-8 SQL strings.
• WEPG_MODE_WIRE: PostgreSQL wire protocol frames (optional, may be unsupported).

wepg_config

Configuration for wepg_init.

Field	Type	Description
pgdata_path	const char *	Required. Absolute path to the data directory.
temp_path	const char *	Optional. Temporary directory path; defaults to pgdata_path if NULL.
flags	uint32_t	Bitmask of WEPG_FLAG_*.
max_response_bytes	uint32_t	Optional. If non-zero, caps response size and returns WEPG_ERR_BUFFER_TOO_SMALL on overflow.

WEPG_FLAG_*

Flag	Value	Meaning
WEPG_FLAG_ENABLE_WIRE	1 << 0	Enables wire mode if implemented.
WEPG_FLAG_READONLY	1 << 1	Enforces read-only execution.
WEPG_FLAG_DISABLE_DYNAMIC_EXT	1 << 2	Disables dynamic extensions.
WEPG_FLAG_NO_AUTO_INITDB	1 << 3	Prevents automatic template copy on init.

wepg_request

Field	Type	Description
mode	wepg_mode	Request mode (WEPG_MODE_SQL recommended).
bytes	const uint8_t *	Request payload (SQL or wire frames).
len	size_t	Length of payload.

wepg_response

Host-managed output buffer used by wepg_step.

Field	Type	Description
bytes	uint8_t *	Output buffer allocated by the host.
len	size_t	Number of bytes written by the engine.
capacity	size_t	Capacity of the output buffer.
rows	int64_t	Number of rows produced (0 for no rows or unknown).

wepg_log_fn

typedef void (*wepg_log_fn)(int level, const char *msg, void *ctx);

Optional logger callback for engine messages.

SQL mode response frame

SQL mode responses use a Worka-specific binary frame. It is stable across bindings and not the PostgreSQL wire protocol.

u32  version          // MUST be 1
u32  column_count
u32  row_count         // 0 if no rows; MAY be 0 for unknown
repeat column_count:
  u32 name_len
  bytes name           // UTF-8 column name
  u32 type_oid         // PostgreSQL type OID
  i16 type_len         // -1 if variable length
  i32 type_mod         // -1 if not applicable
repeat row_count:
  repeat column_count:
    i32 value_len      // -1 for NULL
    bytes value        // raw bytes in PostgreSQL text format

If row_count is unknown, it may be zero while rows are still emitted. In that case, parse until the end of the response buffer.

Function reference

wepg_abi_version

uint32_t wepg_abi_version(void);

Returns the ABI version as a 32-bit integer. The high 16 bits are the major version, the low 16 bits are the minor version. Hosts should check the major version before calling into the library.

wepg_version_string

const char *wepg_version_string(void);

Returns a null-terminated string describing the WorkaDB version. The string is owned by the library and must not be freed by the caller.

wepg_set_logger

void wepg_set_logger(wepg_log_fn fn, void *ctx);

Installs a logger callback. When set, the engine will emit log messages to fn(level, msg, ctx).

Parameters:

• fn: Logger callback. Pass NULL to disable logging.
• ctx: Opaque pointer forwarded to the callback.

wepg_init

wepg_status wepg_init(const wepg_config *config, wepg_handle *out);

Initializes an engine instance.

Parameters:

• config: Configuration struct (must include pgdata_path).
• out: Output pointer that receives the handle on success.

Returns:

• WEPG_OK on success.
• WEPG_ERR_INVALID_CONFIG if config or pointers are invalid.
• WEPG_ERR_INITDB_FAILED if automatic initdb fails and WEPG_FLAG_NO_AUTO_INITDB is not set.

wepg_initdb

wepg_status wepg_initdb(wepg_handle handle);

Ensures the data directory exists using the template-based init path. It is safe to call multiple times.

Parameters:

• handle: Engine handle.

Returns:

• WEPG_OK on success.
• WEPG_ERR_INVALID_CONFIG if the handle is invalid.
• WEPG_ERR_INITDB_FAILED if template copy fails.

wepg_step

wepg_status wepg_step(
    wepg_handle handle,
    const wepg_request *request,
    wepg_response *response
);

Executes exactly one request.

Parameters:

• handle: Engine handle.
• request: Request payload and mode.
• response: Host-managed output buffer and metadata fields.

Returns:

• WEPG_OK on success.
• WEPG_ERR_INVALID_CONFIG if inputs are invalid.
• WEPG_ERR_UNSUPPORTED if WEPG_MODE_WIRE is requested but not implemented.
• WEPG_ERR_BUFFER_TOO_SMALL if response->capacity is too small or exceeds max_response_bytes.
• WEPG_ERR_EXEC_FAILED if SQL execution fails (details in wepg_last_error).

Notes:

• response->bytes must be allocated by the host and remain valid for the call.
• response->len and response->rows are filled by the engine.

wepg_reset

wepg_status wepg_reset(wepg_handle handle);

Clears session state and resets the I/O buffers without deleting data.

Parameters:

• handle: Engine handle.

Returns:

• WEPG_OK on success.
• WEPG_ERR_INVALID_CONFIG if the handle is invalid.

wepg_shutdown

wepg_status wepg_shutdown(wepg_handle handle);

Shuts down the engine and releases resources. The handle becomes invalid after this call.

Parameters:

• handle: Engine handle.

Returns:

• WEPG_OK on success.
• WEPG_ERR_INVALID_CONFIG if the handle is invalid.

wepg_last_error

const char *wepg_last_error(wepg_handle handle);

Returns the last error message associated with the handle. The returned string is owned by the engine and is valid until the next API call on the same handle.

Error handling

All API calls return wepg_status. When a call fails, read the error string with wepg_last_error to retrieve the detailed reason for the last failure.