fsqlite-c-api

SQLite C API compatibility shim for FrankenSQLite. Provides a drop-in replacement for the most commonly used sqlite3_* functions via C FFI.

Overview

fsqlite-c-api exposes FrankenSQLite through the standard SQLite C API, making it possible to link existing C/C++ applications against FrankenSQLite without code changes. The crate builds as a cdylib (shared library), staticlib (static library), and rlib (Rust library).

The shim wraps the Rust Connection type behind opaque Sqlite3 and Sqlite3Stmt handles, translating between C types and Rust types at the boundary. All SQLite result codes (SQLITE_OK, SQLITE_ERROR, SQLITE_ROW, SQLITE_DONE, etc.) and column type constants (SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB, SQLITE_NULL) are exported.

Built-in observability: every API call increments an atomic counter, accessible via compat_metrics_snapshot(). Tracing spans are emitted at INFO level with the compat_api span name.

Position in the dependency graph:

C/C++ application
  --> fsqlite-c-api (this crate) -- C FFI boundary
    --> fsqlite (public API facade)
      --> fsqlite-core (engine)
        --> fsqlite-parser, fsqlite-planner, fsqlite-vdbe, ...

Dependencies: fsqlite, fsqlite-error, fsqlite-types.

Note: This crate allows unsafe_code (required for FFI) while the rest of the workspace forbids it.

Exported FFI Functions

• sqlite3_open -- Open a database connection.
• sqlite3_close -- Close a database connection.
• sqlite3_exec -- Execute SQL with a callback for each result row.
• sqlite3_free -- Free memory allocated by sqlite3_exec error messages.
• sqlite3_prepare_v2 -- Compile SQL into a prepared statement.
• sqlite3_step -- Advance a prepared statement to the next result row.
• sqlite3_finalize -- Destroy a prepared statement.
• sqlite3_reset -- Reset a prepared statement for re-execution.
• sqlite3_column_count -- Number of columns in the result set.
• sqlite3_column_type -- Datatype of a result column.
• sqlite3_column_int / sqlite3_column_int64 -- Integer column accessors.
• sqlite3_column_double -- Float column accessor.
• sqlite3_column_text -- Text column accessor.
• sqlite3_column_blob -- Blob column accessor.
• sqlite3_column_bytes -- Byte length of a column value.
• sqlite3_errmsg -- Last error message.
• sqlite3_errcode -- Last error code.
• sqlite3_changes -- Number of rows changed by the last DML statement.

Key Types

• Sqlite3 -- Opaque database connection handle (wraps Connection + last-error state).
• Sqlite3Stmt -- Opaque prepared statement handle (wraps SQL string, row cache, cursor position, and column metadata).
• CompatMetricsSnapshot -- Point-in-time counters for each API function (open, close, exec, prepare, step, finalize, column, errmsg).

Usage (from C)

#include <stdio.h>

// Link against libfsqlite_c_api.so / libfsqlite_c_api.a
typedef struct Sqlite3 sqlite3;
typedef struct Sqlite3Stmt sqlite3_stmt;

extern int sqlite3_open(const char *filename, sqlite3 **ppDb);
extern int sqlite3_prepare_v2(sqlite3 *db, const char *sql, int nByte,
                              sqlite3_stmt **ppStmt, const char **pzTail);
extern int sqlite3_step(sqlite3_stmt *stmt);
extern const char *sqlite3_column_text(sqlite3_stmt *stmt, int iCol);
extern int sqlite3_finalize(sqlite3_stmt *stmt);
extern int sqlite3_close(sqlite3 *db);

int main(void) {
    sqlite3 *db;
    sqlite3_open(":memory:", &db);

    sqlite3_stmt *stmt;
    sqlite3_prepare_v2(db, "SELECT 'hello, fsqlite!';", -1, &stmt, NULL);

    if (sqlite3_step(stmt) == 101 /* SQLITE_ROW? -- use 100 for ROW */) {
        printf("%s\n", sqlite3_column_text(stmt, 0));
    }

    sqlite3_finalize(stmt);
    sqlite3_close(db);
    return 0;
}

Usage (from Rust, for metrics)

use fsqlite_c_api::{compat_metrics_snapshot, reset_compat_metrics};

let snapshot = compat_metrics_snapshot();
println!("Total API calls: {}", snapshot.total());

License

MIT (with OpenAI/Anthropic Rider) -- see workspace root LICENSE file.