use std::cell::RefCell;
use std::ffi::{CStr, CString};
use std::os::raw::c_char;
use std::panic::{catch_unwind, AssertUnwindSafe};
use std::ptr;
use crate::{Database, PreparedStatement};
#[cfg(all(feature = "encryption", not(target_arch = "wasm32")))]
pub mod vault;
pub struct PvDb {
inner: Database,
}
pub struct PvStmt {
inner: PreparedStatement,
}
thread_local! {
static LAST_ERROR: RefCell<Option<CString>> = const { RefCell::new(None) };
}
fn set_last_error(msg: impl Into<Vec<u8>>) {
let bytes: Vec<u8> = msg
.into()
.into_iter()
.map(|b| if b == 0 { b'?' } else { b })
.collect();
let cstr = CString::new(bytes).unwrap_or_else(|_| CString::new("error").unwrap());
LAST_ERROR.with(|e| *e.borrow_mut() = Some(cstr));
}
fn clear_last_error() {
LAST_ERROR.with(|e| *e.borrow_mut() = None);
}
fn guard<T>(on_panic: T, f: impl FnOnce() -> T) -> T {
match catch_unwind(AssertUnwindSafe(f)) {
Ok(v) => v,
Err(_) => {
set_last_error("panic in a PicoVolt FFI call");
on_panic
}
}
}
unsafe fn cstr_to_str<'a>(p: *const c_char) -> Option<&'a str> {
if p.is_null() {
return None;
}
CStr::from_ptr(p).to_str().ok()
}
fn string_to_c(s: String) -> *mut c_char {
match CString::new(s) {
Ok(c) => c.into_raw(),
Err(_) => {
set_last_error("result contained an interior NUL byte");
ptr::null_mut()
}
}
}
#[no_mangle]
pub extern "C" fn pv_version() -> *const c_char {
concat!(env!("CARGO_PKG_VERSION"), "\0").as_ptr() as *const c_char
}
#[no_mangle]
pub extern "C" fn pv_last_error() -> *const c_char {
LAST_ERROR.with(|e| match &*e.borrow() {
Some(s) => s.as_ptr(),
None => ptr::null(),
})
}
#[no_mangle]
pub extern "C" fn pv_open_memory() -> *mut PvDb {
guard(ptr::null_mut(), || {
clear_last_error();
Box::into_raw(Box::new(PvDb {
inner: Database::open_memory(),
}))
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_open_dev(path: *const c_char) -> *mut PvDb {
guard(ptr::null_mut(), || {
clear_last_error();
let Some(path) = (unsafe { cstr_to_str(path) }) else {
set_last_error("pv_open_dev: path is NULL or not valid UTF-8");
return ptr::null_mut();
};
match Database::open_dev(path) {
Ok(inner) => Box::into_raw(Box::new(PvDb { inner })),
Err(e) => {
set_last_error(e.to_string());
ptr::null_mut()
}
}
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_open_prod(path: *const c_char) -> *mut PvDb {
guard(ptr::null_mut(), || {
clear_last_error();
let Some(path) = (unsafe { cstr_to_str(path) }) else {
set_last_error("pv_open_prod: path is NULL or not valid UTF-8");
return ptr::null_mut();
};
match Database::open_prod(path) {
Ok(inner) => Box::into_raw(Box::new(PvDb { inner })),
Err(e) => {
set_last_error(e.to_string());
ptr::null_mut()
}
}
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_query(db: *mut PvDb, sql: *const c_char) -> *mut c_char {
guard(ptr::null_mut(), || {
clear_last_error();
let Some(db) = (unsafe { db.as_mut() }) else {
set_last_error("pv_query: db handle is NULL");
return ptr::null_mut();
};
let Some(sql) = (unsafe { cstr_to_str(sql) }) else {
set_last_error("pv_query: sql is NULL or not valid UTF-8");
return ptr::null_mut();
};
match db.inner.query(sql) {
Ok(result) => match crate::json::result_to_string(&result) {
Ok(s) => string_to_c(s),
Err(e) => {
set_last_error(e.to_string());
ptr::null_mut()
}
},
Err(e) => {
set_last_error(e.to_string());
ptr::null_mut()
}
}
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_query_params(
db: *mut PvDb,
sql: *const c_char,
params_json: *const c_char,
) -> *mut c_char {
guard(ptr::null_mut(), || {
clear_last_error();
let Some(db) = (unsafe { db.as_mut() }) else {
set_last_error("pv_query_params: db handle is NULL");
return ptr::null_mut();
};
let Some(sql) = (unsafe { cstr_to_str(sql) }) else {
set_last_error("pv_query_params: sql is NULL or not valid UTF-8");
return ptr::null_mut();
};
let Some(pj) = (unsafe { cstr_to_str(params_json) }) else {
set_last_error("pv_query_params: params is NULL or not valid UTF-8");
return ptr::null_mut();
};
let values = match json_params_to_values("pv_query_params", pj) {
Ok(values) => values,
Err(error) => {
set_last_error(error);
return ptr::null_mut();
}
};
match db.inner.query_with(sql, &values) {
Ok(result) => match crate::json::result_to_string(&result) {
Ok(s) => string_to_c(s),
Err(e) => {
set_last_error(e.to_string());
ptr::null_mut()
}
},
Err(e) => {
set_last_error(e.to_string());
ptr::null_mut()
}
}
})
}
#[cfg(any(feature = "full-text", feature = "vector-search"))]
#[no_mangle]
pub unsafe extern "C" fn pv_retrieve(db: *mut PvDb, request: *const c_char) -> *mut c_char {
guard(ptr::null_mut(), || {
clear_last_error();
let (Some(db), Some(request)) = (unsafe { db.as_mut() }, unsafe { cstr_to_str(request) })
else {
set_last_error("pv_retrieve: invalid handle or request");
return ptr::null_mut();
};
match db.inner.retrieve_json(request) {
Ok(result) => string_to_c(result),
Err(error) => {
set_last_error(error.to_string());
ptr::null_mut()
}
}
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_prepare(db: *const PvDb, sql: *const c_char) -> *mut PvStmt {
guard(ptr::null_mut(), || {
clear_last_error();
let Some(db) = (unsafe { db.as_ref() }) else {
set_last_error("pv_prepare: db handle is NULL");
return ptr::null_mut();
};
let Some(sql) = (unsafe { cstr_to_str(sql) }) else {
set_last_error("pv_prepare: sql is NULL or not valid UTF-8");
return ptr::null_mut();
};
match db.inner.prepare(sql) {
Ok(inner) => Box::into_raw(Box::new(PvStmt { inner })),
Err(error) => {
set_last_error(error.to_string());
ptr::null_mut()
}
}
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_stmt_parameter_count(stmt: *const PvStmt) -> usize {
guard(0, || {
clear_last_error();
match unsafe { stmt.as_ref() } {
Some(stmt) => stmt.inner.parameter_count(),
None => {
set_last_error("pv_stmt_parameter_count: statement handle is NULL");
0
}
}
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_stmt_execute(
stmt: *const PvStmt,
db: *mut PvDb,
params_json: *const c_char,
) -> *mut c_char {
guard(ptr::null_mut(), || {
clear_last_error();
let Some(stmt) = (unsafe { stmt.as_ref() }) else {
set_last_error("pv_stmt_execute: statement handle is NULL");
return ptr::null_mut();
};
let Some(db) = (unsafe { db.as_mut() }) else {
set_last_error("pv_stmt_execute: db handle is NULL");
return ptr::null_mut();
};
let Some(pj) = (unsafe { cstr_to_str(params_json) }) else {
set_last_error("pv_stmt_execute: params is NULL or not valid UTF-8");
return ptr::null_mut();
};
let values = match json_params_to_values("pv_stmt_execute", pj) {
Ok(values) => values,
Err(error) => {
set_last_error(error);
return ptr::null_mut();
}
};
match stmt.inner.execute(&mut db.inner, &values) {
Ok(result) => match crate::json::result_to_string(&result) {
Ok(json) => string_to_c(json),
Err(error) => {
set_last_error(error.to_string());
ptr::null_mut()
}
},
Err(error) => {
set_last_error(error.to_string());
ptr::null_mut()
}
}
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_stmt_close(stmt: *mut PvStmt) {
guard((), || {
if !stmt.is_null() {
drop(unsafe { Box::from_raw(stmt) });
}
});
}
fn json_params_to_values(function: &str, params_json: &str) -> Result<Vec<crate::Value>, String> {
let parsed: serde_json::Value = serde_json::from_str(params_json)
.map_err(|error| format!("{function}: invalid params JSON: {error}"))?;
let serde_json::Value::Array(array) = parsed else {
return Err(format!("{function}: params must be a JSON array"));
};
array
.into_iter()
.map(|value| json_to_value(value).map_err(|error| format!("{function}: {error}")))
.collect()
}
fn json_to_value(v: serde_json::Value) -> Result<crate::Value, String> {
use crate::Value;
use serde_json::Value as J;
match v {
J::Null => Ok(Value::Null),
J::Bool(b) => Ok(Value::Int(if b { 1 } else { 0 })),
J::Number(n) => {
if let Some(i) = n.as_i64() {
Ok(Value::Int(i))
} else if n.as_u64().is_some() {
Err("integer parameter exceeds the i64 range".into())
} else if let Some(f) = n.as_f64() {
let scaled = f * 1_000_000.0;
if !scaled.is_finite() || scaled.abs() >= 1.7e38 {
Err("numeric parameter out of range".into())
} else {
Ok(Value::Decimal(scaled.round() as i128))
}
} else {
Err("numeric parameter out of range".into())
}
}
J::String(s) => Ok(Value::Text(s)),
J::Array(_) | J::Object(_) => Err("array and object parameters are not supported".into()),
}
}
#[no_mangle]
pub unsafe extern "C" fn pv_import_sql(db: *mut PvDb, dump: *const c_char) -> *mut c_char {
guard(ptr::null_mut(), || {
clear_last_error();
let Some(db) = (unsafe { db.as_mut() }) else {
set_last_error("pv_import_sql: db handle is NULL");
return ptr::null_mut();
};
let Some(dump) = (unsafe { cstr_to_str(dump) }) else {
set_last_error("pv_import_sql: dump is NULL or not valid UTF-8");
return ptr::null_mut();
};
let report = db.inner.import_sql(dump);
let json = serde_json::json!({
"executed": report.executed,
"skipped": report.skipped,
"errors": report.errors,
});
match serde_json::to_string(&json) {
Ok(s) => string_to_c(s),
Err(e) => {
set_last_error(e.to_string());
ptr::null_mut()
}
}
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_current_tx(db: *const PvDb) -> u64 {
guard(0, || {
clear_last_error();
match unsafe { db.as_ref() } {
Some(db) => db.inner.current_tx(),
None => {
set_last_error("pv_current_tx: db handle is NULL");
0
}
}
})
}
fn transaction_control(
db: *mut PvDb,
function: &str,
operation: impl FnOnce(&mut Database) -> crate::Result<()>,
) -> i32 {
clear_last_error();
let Some(db) = (unsafe { db.as_mut() }) else {
set_last_error(format!("{function}: db handle is NULL"));
return 0;
};
match operation(&mut db.inner) {
Ok(()) => 1,
Err(error) => {
set_last_error(error.to_string());
0
}
}
}
fn json_result<T: serde::Serialize>(result: crate::Result<T>) -> *mut c_char {
match result.and_then(|v| serde_json::to_string(&v).map_err(Into::into)) {
Ok(s) => string_to_c(s),
Err(error) => {
set_last_error(error.to_string());
ptr::null_mut()
}
}
}
#[no_mangle]
pub unsafe extern "C" fn pv_execute_many(
db: *mut PvDb,
sql: *const c_char,
rows_json: *const c_char,
) -> *mut c_char {
guard(ptr::null_mut(), || {
clear_last_error();
let (Some(db), Some(sql), Some(rows)) = (
unsafe { db.as_mut() },
unsafe { cstr_to_str(sql) },
unsafe { cstr_to_str(rows_json) },
) else {
set_last_error("pv_execute_many: null handle or invalid UTF-8 input");
return ptr::null_mut();
};
let result = (|| -> crate::Result<_> {
let rows: Vec<Vec<serde_json::Value>> = serde_json::from_str(rows)?;
let rows: Vec<Vec<crate::Value>> = rows
.into_iter()
.map(|row| {
row.into_iter()
.map(|v| json_to_value(v).map_err(crate::PvError::Query))
.collect()
})
.collect::<crate::Result<_>>()?;
Ok(serde_json::json!({"mutated":db.inner.execute_many(sql,&rows)?}))
})();
json_result(result)
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_enable_commit_log(
db: *mut PvDb,
transaction_bytes: u64,
retained_bytes: u64,
retained_commits: usize,
) -> i32 {
guard(0, || {
transaction_control(db, "pv_enable_commit_log", |db| {
let mut options = crate::CommitLogOptions::default();
if transaction_bytes != 0 {
options.max_transaction_bytes = transaction_bytes;
}
if retained_bytes != 0 {
options.max_retained_bytes = retained_bytes;
}
if retained_commits != 0 {
options.max_retained_commits = retained_commits;
}
db.enable_commit_log(options)
})
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_commit_log_status(db: *const PvDb) -> *mut c_char {
guard(ptr::null_mut(), || {
clear_last_error();
let Some(db) = (unsafe { db.as_ref() }) else {
set_last_error("pv_commit_log_status: null handle");
return ptr::null_mut();
};
json_result(db.inner.commit_log_status())
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_changes_since(
db: *const PvDb,
after: u64,
limit: usize,
) -> *mut c_char {
guard(ptr::null_mut(), || {
clear_last_error();
let Some(db) = (unsafe { db.as_ref() }) else {
set_last_error("pv_changes_since: null handle");
return ptr::null_mut();
};
json_result(db.inner.changes_since(after, limit))
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_prune_changes(db: *mut PvDb, through: u64) -> i32 {
guard(0, || {
transaction_control(db, "pv_prune_changes", |db| db.prune_changes(through))
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_begin_transaction(db: *mut PvDb) -> i32 {
guard(0, || {
transaction_control(db, "pv_begin_transaction", Database::begin_transaction)
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_commit_transaction(db: *mut PvDb) -> i32 {
guard(0, || {
transaction_control(db, "pv_commit_transaction", Database::commit_transaction)
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_rollback_transaction(db: *mut PvDb) -> i32 {
guard(0, || {
transaction_control(
db,
"pv_rollback_transaction",
Database::rollback_transaction,
)
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_in_transaction(db: *const PvDb) -> i32 {
guard(0, || {
clear_last_error();
match unsafe { db.as_ref() } {
Some(db) => i32::from(db.inner.in_transaction()),
None => {
set_last_error("pv_in_transaction: db handle is NULL");
0
}
}
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_export(db: *mut PvDb, out_len: *mut usize) -> *mut u8 {
guard(ptr::null_mut(), || {
clear_last_error();
if out_len.is_null() {
set_last_error("pv_export: out_len is NULL");
return ptr::null_mut();
}
let Some(db) = (unsafe { db.as_mut() }) else {
set_last_error("pv_export: db handle is NULL");
unsafe { *out_len = 0 };
return ptr::null_mut();
};
match db.inner.bake_to_bytes() {
Ok(bytes) => {
let len = bytes.len();
let mut boxed = bytes.into_boxed_slice();
let ptr = boxed.as_mut_ptr();
std::mem::forget(boxed);
unsafe { *out_len = len };
ptr
}
Err(e) => {
set_last_error(e.to_string());
unsafe { *out_len = 0 };
ptr::null_mut()
}
}
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_import(bytes: *const u8, len: usize) -> *mut PvDb {
guard(ptr::null_mut(), || {
clear_last_error();
if bytes.is_null() {
set_last_error("pv_import: bytes is NULL");
return ptr::null_mut();
}
let slice = unsafe { std::slice::from_raw_parts(bytes, len) };
match Database::import_bytes(slice) {
Ok(inner) => Box::into_raw(Box::new(PvDb { inner })),
Err(e) => {
set_last_error(e.to_string());
ptr::null_mut()
}
}
})
}
#[no_mangle]
pub unsafe extern "C" fn pv_string_free(s: *mut c_char) {
if !s.is_null() {
drop(unsafe { CString::from_raw(s) });
}
}
#[no_mangle]
pub unsafe extern "C" fn pv_bytes_free(ptr: *mut u8, len: usize) {
if !ptr.is_null() {
drop(unsafe { Box::from_raw(std::ptr::slice_from_raw_parts_mut(ptr, len)) });
}
}
#[no_mangle]
pub unsafe extern "C" fn pv_close(db: *mut PvDb) {
guard((), || {
if !db.is_null() {
let mut db = unsafe { Box::from_raw(db) };
if db.inner.in_transaction() {
let _ = db.inner.rollback_transaction();
}
drop(db);
}
});
}
#[cfg(test)]
mod tests {
use super::*;
unsafe fn run(db: *mut PvDb, sql: &str) -> Option<String> {
let c = CString::new(sql).unwrap();
let res = pv_query(db, c.as_ptr());
if res.is_null() {
return None;
}
let s = CStr::from_ptr(res).to_str().unwrap().to_owned();
pv_string_free(res);
Some(s)
}
#[test]
fn roundtrip_memory() {
unsafe {
let db = pv_open_memory();
assert!(!db.is_null());
assert!(run(db, "CREATE TABLE t (id, name)")
.unwrap()
.contains("\"done\":true"));
assert!(run(db, "INSERT INTO t VALUES (1, 'alice')")
.unwrap()
.contains("\"mutated\":1"));
let sel = run(db, "SELECT * FROM t").unwrap();
assert!(sel.contains("\"columns\"") && sel.contains("alice"));
assert!(pv_current_tx(db) > 0);
pv_close(db);
}
}
#[test]
fn params_bind_and_escape() {
unsafe {
let db = pv_open_memory();
run(db, "CREATE TABLE u (id, name)").unwrap();
let sql = CString::new("INSERT INTO u VALUES (?, ?)").unwrap();
let p1 = CString::new(r#"[1, "o'brien"]"#).unwrap();
let r1 = pv_query_params(db, sql.as_ptr(), p1.as_ptr());
assert!(!r1.is_null());
pv_string_free(r1);
let p2 = CString::new(r#"[2, "x'); DROP TABLE u; --"]"#).unwrap();
let r2 = pv_query_params(db, sql.as_ptr(), p2.as_ptr());
assert!(!r2.is_null());
pv_string_free(r2);
assert!(run(db, "SELECT COUNT(*) FROM u").unwrap().contains("[[2]]"));
pv_close(db);
}
}
#[test]
fn error_path_sets_last_error() {
unsafe {
let db = pv_open_memory();
clear_last_error();
let bad = pv_query(db, CString::new("SELECT FROM").unwrap().as_ptr());
assert!(bad.is_null());
let err = pv_last_error();
assert!(!err.is_null());
assert!(!CStr::from_ptr(err).to_bytes().is_empty());
pv_close(db);
}
}
#[test]
fn export_import_roundtrip() {
unsafe {
let db = pv_open_memory();
run(db, "CREATE TABLE t (id)").unwrap();
run(db, "INSERT INTO t VALUES (42)").unwrap();
let mut len: usize = 0;
let bytes = pv_export(db, &mut len as *mut usize);
assert!(!bytes.is_null() && len > 0);
let db2 = pv_import(bytes, len);
assert!(!db2.is_null());
assert!(run(db2, "SELECT * FROM t").unwrap().contains("42"));
pv_bytes_free(bytes, len);
pv_close(db);
pv_close(db2);
}
}
#[test]
fn prepared_statement_reuses_validated_template() {
unsafe {
let db = pv_open_memory();
run(db, "CREATE TABLE t (id, name)").unwrap();
let sql = CString::new("INSERT INTO t VALUES (?, ?)").unwrap();
let stmt = pv_prepare(db, sql.as_ptr());
assert!(!stmt.is_null());
assert_eq!(pv_stmt_parameter_count(stmt), 2);
for params in ["[1,\"alice\"]", "[2,\"bob\"]"] {
let params = CString::new(params).unwrap();
let result = pv_stmt_execute(stmt, db, params.as_ptr());
assert!(!result.is_null());
assert!(CStr::from_ptr(result).to_str().unwrap().contains("mutated"));
pv_string_free(result);
}
let wrong_arity = CString::new("[3]").unwrap();
assert!(pv_stmt_execute(stmt, db, wrong_arity.as_ptr()).is_null());
assert!(CStr::from_ptr(pv_last_error())
.to_str()
.unwrap()
.contains("expects 2 parameters"));
pv_stmt_close(stmt);
assert!(run(db, "SELECT COUNT(*) FROM t").unwrap().contains("[[2]]"));
pv_close(db);
}
}
#[test]
fn prepared_statement_rejects_invalid_inputs_without_unwinding() {
unsafe {
let db = pv_open_memory();
let invalid = CString::new("SELECT FROM").unwrap();
assert!(pv_prepare(db, invalid.as_ptr()).is_null());
assert!(!pv_last_error().is_null());
assert!(pv_prepare(ptr::null(), invalid.as_ptr()).is_null());
assert_eq!(pv_stmt_parameter_count(ptr::null()), 0);
let empty = CString::new("[]").unwrap();
assert!(pv_stmt_execute(ptr::null(), db, empty.as_ptr()).is_null());
pv_stmt_close(ptr::null_mut());
pv_close(db);
}
}
#[test]
fn explicit_transaction_round_trips_through_c_abi() {
unsafe {
let db = pv_open_memory();
run(db, "CREATE TABLE t (id)").unwrap();
assert_eq!(pv_begin_transaction(db), 1);
assert_eq!(pv_in_transaction(db), 1);
run(db, "INSERT INTO t VALUES (1)").unwrap();
assert_eq!(pv_rollback_transaction(db), 1);
assert_eq!(pv_in_transaction(db), 0);
assert!(run(db, "SELECT COUNT(*) FROM t").unwrap().contains("[[0]]"));
assert_eq!(pv_begin_transaction(db), 1);
run(db, "INSERT INTO t VALUES (2)").unwrap();
assert_eq!(pv_commit_transaction(db), 1);
assert!(run(db, "SELECT COUNT(*) FROM t").unwrap().contains("[[1]]"));
pv_close(db);
}
}
#[test]
fn null_arguments_are_safe() {
unsafe {
let sql = CString::new("SELECT 1").unwrap();
assert!(pv_query(ptr::null_mut(), sql.as_ptr()).is_null());
assert_eq!(pv_current_tx(ptr::null()), 0);
pv_close(ptr::null_mut());
pv_string_free(ptr::null_mut());
pv_bytes_free(ptr::null_mut(), 0);
let v = CStr::from_ptr(pv_version()).to_str().unwrap();
assert!(v.chars().next().unwrap().is_ascii_digit());
}
}
}