use picovolt::{Database, PvError, QueryResult, Value};
use serde_json::{Map, Value as JsonValue};
use std::collections::BTreeMap;
use std::error::Error;
use std::fs::{self, File};
use std::io::{BufRead, BufReader, BufWriter, Write};
use std::path::{Path, PathBuf};
type CliResult<T> = Result<T, Box<dyn Error>>;
#[cfg(all(feature = "encryption", not(target_arch = "wasm32")))]
mod crypto;
#[cfg(all(feature = "data-tools", not(target_arch = "wasm32")))]
mod data_tools;
fn main() {
if let Err(error) = run(std::env::args().skip(1).collect()) {
eprintln!("pv: {error}");
std::process::exit(1);
}
}
fn run(args: Vec<String>) -> CliResult<()> {
match args.first().map(String::as_str) {
#[cfg(all(feature = "encryption", not(target_arch = "wasm32")))]
Some("crypto") => crypto::crypto(&args[1..]),
#[cfg(all(feature = "encryption", not(target_arch = "wasm32")))]
Some("vault") => crypto::vault(&args[1..]),
Some("--version") | Some("-V") => {
println!("pv {}", env!("CARGO_PKG_VERSION"));
Ok(())
}
Some("query") if args.len() >= 3 => {
let mut db = open_database(&args[1])?;
print_result(db.query(&args[2..].join(" "))?)
}
Some("explain") if args.len() >= 3 => {
let db = open_existing_database(&args[1])?;
print_result(db.explain(&args[2..].join(" "))?)
}
#[cfg(any(feature = "full-text", feature = "vector-search"))]
Some("retrieve") if args.len() == 3 => {
use std::io::Read;
let mut input = String::new();
File::open(&args[2])?
.take(131073)
.read_to_string(&mut input)?;
if input.len() > 131072 {
return Err("Retrieval request exceeds 128 KiB".into());
}
let mut db = open_existing_database(&args[1])?;
println!("{}", db.retrieve_json(&input)?);
Ok(())
}
Some("inspect") if args.len() >= 2 => {
let db = open_existing_database(&args[1])?;
let stats = db.inspect_stats()?;
if args.get(2).map(String::as_str) == Some("--json") && args.len() == 3 {
println!("{}", serde_json::to_string_pretty(&stats)?);
} else if args.len() == 2 {
println!("transaction: {}\nformat: {}\nstorage: {}\npages: {} ({} bytes; {} orphaned)\nCAS: {} blobs, {} bytes", stats.current_transaction, stats.format_version, stats.storage_mode, stats.allocated_pages, stats.allocated_page_bytes, stats.orphaned_pages, stats.cas.blobs, stats.cas.stored_bytes);
for table in stats.tables {
println!("table: {}\n rows: {} live / {} versions\n pages: {} ({} used, {} free bytes)\n compression: {}", table.name, table.live_rows, table.row_versions, table.pages, table.used_page_bytes, table.free_page_bytes, table.compression.codec);
for index in table.indexes {
println!(
" index: {} ({} entries, {} keys, {} encoded bytes)",
index.column, index.entries, index.distinct_keys, index.encoded_bytes
);
}
}
} else {
return Err("usage: pv inspect <database> [--json]".into());
}
Ok(())
}
Some("history") if args.len() >= 2 => history_command(&args[1..]),
Some("diff") => diff_command(&args[1..]),
Some("changes") if args.len() == 3 || args.len() == 4 => {
let db = open_existing_database(&args[1])?;
let after = args[2].parse::<u64>()?;
let limit = args
.get(3)
.map(|s| s.parse::<usize>())
.transpose()?
.unwrap_or(64);
for change in db.changes_since(after, limit)? {
println!("{}", serde_json::to_string(&change)?);
}
Ok(())
}
Some("log-prune") if args.len() == 3 => {
let mut db = open_existing_database(&args[1])?;
db.prune_changes(args[2].parse::<u64>()?)?;
Ok(())
}
Some("log-enable") if args.len() == 2 => {
let mut db = open_database(&args[1])?;
db.enable_commit_log(picovolt::CommitLogOptions::default())?;
db.begin_transaction()?;
db.commit_transaction()?;
println!(
"commit log enabled; inspect usage with: pv log-status {}",
args[1]
);
Ok(())
}
Some("log-status") if args.len() == 2 => {
let db = open_existing_database(&args[1])?;
println!(
"{}",
serde_json::to_string_pretty(&db.commit_log_status()?)?
);
Ok(())
}
Some("batch") if args.len() == 4 => {
let mut db = open_database(&args[1])?;
let rows: Vec<Vec<serde_json::Value>> = serde_json::from_slice(&fs::read(&args[3])?)?;
let rows = rows
.into_iter()
.map(|row| row.iter().map(json_to_value).collect())
.collect::<CliResult<Vec<Vec<Value>>>>()?;
println!(
"{}",
serde_json::json!({"mutated":db.execute_many(&args[2],&rows)?})
);
Ok(())
}
Some("migrate") => migrate_command(&args[1..]),
Some("compact") => compact_command(&args[1..]),
Some("bake") if args.len() == 3 || (args.len() == 4 && args[3] == "--resume") => {
let mut db = open_existing_database(&args[1])?;
if args.len() == 4 {
db.bake_resumable(&args[2])?;
} else {
db.bake(&args[2])?;
}
println!("wrote {}", args[2]);
Ok(())
}
Some("import") => import_command(&args[1..]),
Some("export") => export_command(&args[1..]),
Some("dataset") => dataset_command(&args[1..]),
Some("help") | Some("--help") | Some("-h") | None => {
print_help();
Ok(())
}
Some(command) => {
Err(format!("unknown or incomplete command `{command}`; run `pv help`").into())
}
}
}
fn migrate_command(args: &[String]) -> CliResult<()> {
if args.len() < 2 {
return Err(
"usage: pv migrate <source.pvdb> <destination.pvdb> [--dry-run] [--backup <backup.pvdb>] [--json]"
.into(),
);
}
let source = Path::new(&args[0]);
let destination = Path::new(&args[1]);
let mut backup = None;
let mut json = false;
let mut dry_run = false;
let mut index = 2usize;
while index < args.len() {
match args[index].as_str() {
"--backup" if backup.is_none() => {
let value = args
.get(index + 1)
.filter(|value| !value.starts_with("--"))
.ok_or("--backup requires a path")?;
backup = Some(PathBuf::from(value));
index += 2;
}
"--backup" => return Err("--backup may be specified only once".into()),
"--json" if !json => {
json = true;
index += 1;
}
"--json" => return Err("--json may be specified only once".into()),
"--dry-run" if !dry_run => {
dry_run = true;
index += 1;
}
"--dry-run" => return Err("--dry-run may be specified only once".into()),
other => return Err(format!("unknown pv migrate option `{other}`").into()),
}
}
if dry_run {
let plan = picovolt::plan_file_migration(source, destination, backup.as_deref())?;
if json {
println!("{}", serde_json::to_string_pretty(&plan)?);
} else {
println!(
"dry run: format {} -> {}; {} table(s), {} record version(s), {} bytes\nverification: {}\nno files were created",
plan.source_format,
plan.target_format,
plan.tables,
plan.row_versions,
plan.source_bytes,
plan.verification_hash
);
}
return Ok(());
}
let report =
picovolt::migrate_file(source, destination, &picovolt::MigrationOptions { backup })?;
if json {
println!("{}", serde_json::to_string_pretty(&report)?);
} else {
println!(
"migrated {} -> {} (format {} -> {}, {} record version(s), verified {})",
report.source.display(),
report.destination.display(),
report.source_format,
report.target_format,
report.row_versions,
report.verification_hash
);
if let Some(backup) = report.backup {
println!(
"rollback: remove the new destination and reopen the unchanged source; exact backup: {}",
backup.display()
);
} else {
println!("rollback: remove the new destination and reopen the unchanged source");
}
}
Ok(())
}
fn compact_command(args: &[String]) -> CliResult<()> {
if args.is_empty() {
return Err("usage: pv compact <workspace> [--max-pages <count>] [--json]".into());
}
let mut max_pages = None;
let mut json = false;
let mut index = 1usize;
while index < args.len() {
match args[index].as_str() {
"--max-pages" if max_pages.is_none() => {
let value = args
.get(index + 1)
.filter(|value| !value.starts_with("--"))
.ok_or("--max-pages requires a non-negative integer")?;
max_pages = Some(value.parse::<usize>()?);
index += 2;
}
"--max-pages" => return Err("--max-pages may be specified only once".into()),
"--json" if !json => {
json = true;
index += 1;
}
"--json" => return Err("--json may be specified only once".into()),
other => return Err(format!("unknown pv compact option `{other}`").into()),
}
}
let mut database = open_existing_database(&args[0])?;
if !database.is_writable() {
return Err(
"pv compact requires a development workspace; migrate baked images out-of-place".into(),
);
}
let report = database.compact_step(max_pages.unwrap_or(usize::MAX))?;
if json {
println!("{}", serde_json::to_string_pretty(&report)?);
} else {
println!(
"compacted {} of {} examined page(s); saved {} encoded byte(s); skipped {}",
report.compacted_pages, report.examined_pages, report.saved_bytes, report.skipped_pages
);
}
Ok(())
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ChangeKind {
Removed,
Added,
}
impl ChangeKind {
fn as_str(self) -> &'static str {
match self {
Self::Removed => "removed",
Self::Added => "added",
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
struct RowChange {
kind: ChangeKind,
row: Vec<Value>,
}
fn diff_command(args: &[String]) -> CliResult<()> {
if args.len() < 2 {
return Err(
"usage: pv diff <database> <table> --from <tx> --to <tx> [--format csv|jsonl]".into(),
);
}
let from = parse_tx_option(args, "--from")?;
let to = parse_tx_option(args, "--to")?;
let format = option(args, "--format")
.unwrap_or("csv")
.to_ascii_lowercase();
let db = open_database(&args[0])?;
let (columns, changes) = snapshot_diff(&db, &args[1], from, to)?;
let mut out = BufWriter::new(std::io::stdout().lock());
match format.as_str() {
"csv" => write_diff_csv(&mut out, &columns, &changes)?,
"json" | "jsonl" | "ndjson" => write_diff_jsonl(&mut out, &columns, &changes)?,
_ => return Err(format!("unsupported diff format `{format}`").into()),
}
out.flush()?;
Ok(())
}
fn parse_tx_option(args: &[String], name: &str) -> CliResult<u64> {
let value = required_option(args, name)?;
value.parse().map_err(|_| {
format!("`{name}` must be a non-negative transaction id; got `{value}`").into()
})
}
fn snapshot_diff(
db: &Database,
table: &str,
from: u64,
to: u64,
) -> CliResult<(Vec<String>, Vec<RowChange>)> {
if from > to {
return Err(
format!("`--from` transaction {from} is later than `--to` transaction {to}").into(),
);
}
let current = db.current_tx();
if to > current {
return Err(format!(
"`--to` transaction {to} is later than the database's current transaction {current}"
)
.into());
}
let (from_columns, from_rows) = db.select(table, Some(from))?;
let (to_columns, to_rows) = db.select(table, Some(to))?;
if from_columns != to_columns {
return Err("table schema differs between the requested snapshots".into());
}
let from_counts = row_counts(from_rows);
let to_counts = row_counts(to_rows);
let mut changes = Vec::new();
for (row, from_count) in &from_counts {
let removed = from_count.saturating_sub(to_counts.get(row).copied().unwrap_or(0));
changes.extend((0..removed).map(|_| RowChange {
kind: ChangeKind::Removed,
row: row.clone(),
}));
}
for (row, to_count) in &to_counts {
let added = to_count.saturating_sub(from_counts.get(row).copied().unwrap_or(0));
changes.extend((0..added).map(|_| RowChange {
kind: ChangeKind::Added,
row: row.clone(),
}));
}
Ok((from_columns, changes))
}
fn row_counts(rows: Vec<Vec<Value>>) -> BTreeMap<Vec<Value>, usize> {
let mut counts = BTreeMap::new();
for row in rows {
*counts.entry(row).or_default() += 1;
}
counts
}
fn write_diff_csv(
out: &mut impl Write,
columns: &[String],
changes: &[RowChange],
) -> CliResult<()> {
writeln!(
out,
"_change,{}",
columns
.iter()
.map(|column| csv_escape(column))
.collect::<Vec<_>>()
.join(",")
)?;
for change in changes {
writeln!(
out,
"{},{}",
change.kind.as_str(),
change
.row
.iter()
.map(value_to_csv)
.collect::<Vec<_>>()
.join(",")
)?;
}
Ok(())
}
fn write_diff_jsonl(
out: &mut impl Write,
columns: &[String],
changes: &[RowChange],
) -> CliResult<()> {
for change in changes {
let row: Map<String, JsonValue> = columns
.iter()
.cloned()
.zip(change.row.iter().map(value_to_json))
.collect();
let mut object = Map::new();
object.insert("change".into(), JsonValue::from(change.kind.as_str()));
object.insert("row".into(), JsonValue::Object(row));
serde_json::to_writer(&mut *out, &JsonValue::Object(object))?;
writeln!(out)?;
}
Ok(())
}
fn history_command(args: &[String]) -> CliResult<()> {
let db = open_database(&args[0])?;
let tables = match option(args, "--table") {
Some(table) => vec![table.to_owned()],
None => db.table_names(),
};
let limit = option(args, "--limit")
.map(str::parse::<u64>)
.transpose()?
.unwrap_or(20);
println!("transaction,table,rows");
for (tx, table, rows) in history_rows(&db, &tables, limit)? {
println!("{tx},{},{}", csv_escape(&table), rows);
}
Ok(())
}
fn history_rows(
db: &Database,
tables: &[String],
limit: u64,
) -> Result<Vec<(u64, String, usize)>, PvError> {
if limit == 0 {
return Ok(Vec::new());
}
let current = db.current_tx();
let first = current.saturating_sub(limit.saturating_sub(1));
let mut history = Vec::new();
for tx in first..=current {
for table in tables {
let (_, rows) = db.select(table, Some(tx))?;
history.push((tx, table.clone(), rows.len()));
}
}
Ok(history)
}
fn open_database(path: &str) -> Result<Database, PvError> {
if Path::new(path).is_file() {
Database::open_prod(path)
} else {
Database::open_dev(path)
}
}
fn open_existing_database(path: &str) -> CliResult<Database> {
let p = Path::new(path);
if !p.is_file() && !p.join(picovolt::MANIFEST_FILE).is_file() {
return Err(format!("database does not exist: {path}").into());
}
Ok(open_database(path)?)
}
#[cfg(all(feature = "data-tools", not(target_arch = "wasm32")))]
fn dataset_command(args: &[String]) -> CliResult<()> {
use data_tools::dataset;
match args.first().map(String::as_str) {
Some("keygen") if args.len() == 2 => println!("{}", dataset::generate_key(Path::new(&args[1]))?),
Some("sign") if args.len() >= 2 => {
let key = required_option(args, "--key")?;
let name = required_option(args, "--name")?;
let output = Path::new(required_option(args, "--output")?);
let signed = dataset::sign(Path::new(&args[1]), name, Path::new(key))?;
let parent = output.parent().filter(|p| !p.as_os_str().is_empty()).unwrap_or(Path::new("."));
let mut temp = tempfile::NamedTempFile::new_in(parent)?;
serde_json::to_writer_pretty(temp.as_file_mut(), &signed)?;
temp.as_file().sync_all()?;
temp.persist_noclobber(output)?;
println!("signed {}", output.display());
}
Some("verify") if args.len() >= 3 => {
let result = dataset::verify(Path::new(&args[1]), Path::new(&args[2]), required_option(args, "--public-key")?)?;
println!("verified {} ({} bytes, BLAKE3 {})", result.name, result.size_bytes, result.blake3);
}
_ => return Err("usage: pv dataset keygen <private-key> | sign <image> --key <private-key> --name <name> --output <manifest> | verify <image> <manifest> --public-key <hex>".into()),
}
Ok(())
}
#[cfg(not(all(feature = "data-tools", not(target_arch = "wasm32"))))]
fn dataset_command(_: &[String]) -> CliResult<()> {
Err(
"dataset commands require a native build: cargo install picovolt --features data-tools"
.into(),
)
}
fn import_command(args: &[String]) -> CliResult<()> {
if args.len() < 2 {
return Err(
"usage: pv import <workspace> <input> [--table name] [--format csv|jsonl|sql|parquet|sqlite] [--source-table name]".into(),
);
}
let workspace = &args[0];
let input = PathBuf::from(&args[1]);
let format = option(args, "--format")
.map(str::to_owned)
.or_else(|| {
input
.extension()
.and_then(|v| v.to_str())
.map(str::to_owned)
})
.unwrap_or_else(|| "sql".into())
.to_ascii_lowercase();
let mut db = Database::open_dev(workspace)?;
let imported = match format.as_str() {
"sql" => {
let report = db.import_sql(&fs::read_to_string(&input)?);
for skipped in &report.skipped {
eprintln!("skipped: {skipped}");
}
for failure in &report.errors {
eprintln!("error: {failure}");
}
if !report.errors.is_empty() {
return Err(format!("{} SQL statement(s) failed", report.errors.len()).into());
}
report.executed
}
"csv" => import_csv(&mut db, required_option(args, "--table")?, &input)?,
"json" | "jsonl" | "ndjson" => {
import_jsonl(&mut db, required_option(args, "--table")?, &input)?
}
#[cfg(all(feature = "data-tools", not(target_arch = "wasm32")))]
"parquet" => {
data_tools::import_parquet(&mut db, &input, required_option(args, "--table")?)? as usize
}
#[cfg(all(feature = "data-tools", not(target_arch = "wasm32")))]
"sqlite" | "sqlite3" | "db" => {
let target = required_option(args, "--table")?;
data_tools::import_sqlite(
&mut db,
&input,
option(args, "--source-table").unwrap_or(target),
target,
)? as usize
}
#[cfg(not(all(feature = "data-tools", not(target_arch = "wasm32"))))]
"parquet" | "sqlite" | "sqlite3" | "db" => {
return Err(
"binary imports require: cargo install picovolt --features data-tools".into(),
)
}
_ => return Err(format!("unsupported import format `{format}`").into()),
};
println!("imported {imported} row(s)/statement(s)");
Ok(())
}
fn export_command(args: &[String]) -> CliResult<()> {
if args.len() < 3 {
return Err("usage: pv export <database> <table> <output> [--format csv|jsonl|parquet] [--before tx (Parquet only)]".into());
}
let mut db = open_existing_database(&args[0])?;
let output = PathBuf::from(&args[2]);
let format = option(args, "--format")
.map(str::to_owned)
.or_else(|| {
output
.extension()
.and_then(|v| v.to_str())
.map(str::to_owned)
})
.unwrap_or_else(|| "csv".into())
.to_ascii_lowercase();
#[cfg(all(feature = "data-tools", not(target_arch = "wasm32")))]
if format == "parquet" {
let before = option(args, "--before")
.map(str::parse::<u64>)
.transpose()?;
let count = data_tools::export_parquet(&db, &args[1], &output, before)?;
println!("exported {count} row(s) to {}", output.display());
return Ok(());
}
if format == "parquet" {
return Err("Parquet export requires: cargo install picovolt --features data-tools".into());
}
if !matches!(format.as_str(), "csv" | "json" | "jsonl" | "ndjson") {
return Err(format!("unsupported export format `{format}`").into());
}
if args.iter().any(|arg| arg == "--before") {
return Err("--before is currently supported only for Parquet export".into());
}
let QueryResult::Rows { columns, rows } = db.query(&format!("SELECT * FROM {}", args[1]))?
else {
unreachable!("SELECT always returns rows")
};
let parent = output
.parent()
.filter(|p| !p.as_os_str().is_empty())
.unwrap_or(Path::new("."));
let mut temporary = tempfile::NamedTempFile::new_in(parent)?;
let mut out = BufWriter::new(temporary.as_file_mut());
match format.as_str() {
"csv" => write_csv(&mut out, &columns, &rows)?,
"json" | "jsonl" | "ndjson" => write_jsonl(&mut out, &columns, &rows)?,
_ => return Err(format!("unsupported export format `{format}`").into()),
}
out.flush()?;
drop(out);
temporary.as_file().sync_all()?;
temporary.persist(&output)?;
println!("exported {} row(s) to {}", rows.len(), output.display());
Ok(())
}
fn option<'a>(args: &'a [String], name: &str) -> Option<&'a str> {
args.windows(2)
.find(|pair| pair[0] == name)
.map(|pair| pair[1].as_str())
}
fn required_option<'a>(args: &'a [String], name: &str) -> CliResult<&'a str> {
option(args, name).ok_or_else(|| format!("missing required option `{name}`").into())
}
fn import_csv(db: &mut Database, table: &str, path: &Path) -> CliResult<usize> {
let mut lines = BufReader::new(File::open(path)?).lines();
let header = lines.next().ok_or("CSV input is empty")??;
let columns = parse_csv_record(&header)?;
create_table_if_missing(db, table, &columns)?;
let placeholders = vec!["?"; columns.len()].join(", ");
let sql = format!("INSERT INTO {table} VALUES ({placeholders})");
let mut count = 0;
for (line_number, line) in lines.enumerate() {
let cells = parse_csv_record(&line?)?;
if cells.len() != columns.len() {
return Err(format!(
"CSV line {} has {} fields; expected {}",
line_number + 2,
cells.len(),
columns.len()
)
.into());
}
let values: Vec<Value> = cells.into_iter().map(|cell| parse_scalar(&cell)).collect();
db.query_with(&sql, &values)?;
count += 1;
}
Ok(count)
}
fn parse_csv_record(line: &str) -> CliResult<Vec<String>> {
let mut fields = Vec::new();
let mut field = String::new();
let mut quoted = false;
let mut chars = line.chars().peekable();
while let Some(ch) = chars.next() {
match ch {
'"' if quoted && chars.peek() == Some(&'"') => {
field.push('"');
chars.next();
}
'"' => quoted = !quoted,
',' if !quoted => fields.push(std::mem::take(&mut field)),
_ => field.push(ch),
}
}
if quoted {
return Err("unterminated CSV quote (multiline fields are not supported)".into());
}
fields.push(field);
Ok(fields)
}
fn import_jsonl(db: &mut Database, table: &str, path: &Path) -> CliResult<usize> {
let reader = BufReader::new(File::open(path)?);
let mut columns: Option<Vec<String>> = None;
let mut count = 0;
for (line_number, line) in reader.lines().enumerate() {
let line = line?;
if line.trim().is_empty() {
continue;
}
let JsonValue::Object(object) = serde_json::from_str(&line)? else {
return Err(format!("JSONL line {} is not an object", line_number + 1).into());
};
let names = columns.get_or_insert_with(|| object.keys().cloned().collect());
if count == 0 {
create_table_if_missing(db, table, names)?;
}
let values: Vec<Value> = names
.iter()
.map(|name| json_to_value(object.get(name).unwrap_or(&JsonValue::Null)))
.collect::<CliResult<_>>()?;
let placeholders = vec!["?"; names.len()].join(", ");
db.query_with(
&format!("INSERT INTO {table} VALUES ({placeholders})"),
&values,
)?;
count += 1;
}
Ok(count)
}
fn create_table_if_missing(db: &mut Database, table: &str, columns: &[String]) -> CliResult<()> {
if !db.table_names().iter().any(|name| name == table) {
db.query(&format!("CREATE TABLE {table} ({})", columns.join(", ")))?;
}
Ok(())
}
fn parse_scalar(value: &str) -> Value {
if value.is_empty() || value.eq_ignore_ascii_case("null") {
Value::Null
} else if let Ok(value) = value.parse::<i64>() {
Value::Int(value)
} else if let Ok(value) = value.parse::<f64>() {
Value::Decimal((value * 1_000_000.0).round() as i128)
} else {
Value::Text(value.to_owned())
}
}
fn json_to_value(value: &JsonValue) -> CliResult<Value> {
Ok(match value {
JsonValue::Null => Value::Null,
JsonValue::Bool(value) => Value::Int(i64::from(*value)),
JsonValue::Number(value) if value.is_i64() => Value::Int(value.as_i64().unwrap()),
JsonValue::Number(value) => Value::Decimal(
(value.as_f64().ok_or("JSON number cannot be represented")? * 1_000_000.0).round()
as i128,
),
JsonValue::String(value) => Value::Text(value.clone()),
JsonValue::Array(_) | JsonValue::Object(_) => Value::Text(serde_json::to_string(value)?),
})
}
fn write_csv(out: &mut impl Write, columns: &[String], rows: &[Vec<Value>]) -> CliResult<()> {
writeln!(
out,
"{}",
columns
.iter()
.map(|v| csv_escape(v))
.collect::<Vec<_>>()
.join(",")
)?;
for row in rows {
writeln!(
out,
"{}",
row.iter().map(value_to_csv).collect::<Vec<_>>().join(",")
)?;
}
Ok(())
}
fn csv_escape(value: &str) -> String {
if value.contains([',', '"', '\n', '\r']) {
format!("\"{}\"", value.replace('"', "\"\""))
} else {
value.to_owned()
}
}
fn value_to_csv(value: &Value) -> String {
match value {
Value::Null => String::new(),
Value::Text(value) => csv_escape(value),
_ => csv_escape(&value.to_string()),
}
}
fn write_jsonl(out: &mut impl Write, columns: &[String], rows: &[Vec<Value>]) -> CliResult<()> {
for row in rows {
let object: Map<String, JsonValue> = columns
.iter()
.cloned()
.zip(row.iter().map(value_to_json))
.collect();
serde_json::to_writer(&mut *out, &JsonValue::Object(object))?;
writeln!(out)?;
}
Ok(())
}
fn value_to_json(value: &Value) -> JsonValue {
match value {
Value::Null => JsonValue::Null,
Value::Int(value) => JsonValue::from(*value),
Value::Decimal(value) => JsonValue::from(*value as f64 / 1_000_000.0),
Value::Text(value) => JsonValue::from(value.clone()),
Value::Blob(value) => JsonValue::from(
value
.iter()
.map(|byte| format!("{byte:02x}"))
.collect::<String>(),
),
}
}
fn print_result(result: QueryResult) -> CliResult<()> {
match result {
QueryResult::Rows { columns, rows } => write_csv(&mut std::io::stdout(), &columns, &rows),
QueryResult::Mutated(count) => {
println!("{count} row(s) affected");
Ok(())
}
QueryResult::Done => {
println!("ok");
Ok(())
}
}
}
fn print_help() {
#[cfg(all(feature = "encryption", not(target_arch = "wasm32")))]
println!("{}\n", crypto::HELP);
println!("PicoVolt command-line interface\n");
println!(" pv query <database> <sql>");
#[cfg(any(feature = "full-text", feature = "vector-search"))]
println!(" pv retrieve <database> <request.json> # bounded full-text/vector search");
println!(" pv explain <database> <select-sql>");
println!(" pv inspect <database> [--json]");
println!(" pv history <database> [--table name] [--limit transactions]");
println!(" pv diff <database> <table> --from <tx> --to <tx> [--format csv|jsonl]");
println!(" pv changes <workspace> <after-sequence> [limit]");
println!(" pv log-prune <workspace> <acknowledged-sequence>");
println!(" pv log-enable <workspace> enable synced physical commit logging");
println!(" pv log-status <workspace> show usage, limits and sequence cursors");
println!(" pv batch <workspace> <SQL> <rows.json> atomic parameterized batch");
println!(
" pv migrate <source.pvdb> <destination.pvdb> [--dry-run] [--backup backup.pvdb] [--json]"
);
println!(" pv compact <workspace> [--max-pages count] [--json]");
println!(" pv bake <database> <output.pvdb> [--resume]");
println!(" pv import <workspace> <input> [--table name] [--format csv|jsonl|sql|parquet|sqlite] [--source-table name]");
println!(" pv export <database> <table> <output> [--format csv|jsonl|parquet] [--before tx (Parquet)]");
println!(" pv dataset keygen <private-key>");
println!(" pv dataset sign <image> --key <private-key> --name <name> --output <manifest>");
println!(" pv dataset verify <image> <manifest> --public-key <hex>");
println!(
"\nParquet, SQLite, and dataset signing require a native --features data-tools build."
);
println!("\nA database path ending in a file is opened read-only; a directory is a writable workspace.");
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn csv_quotes_and_scalars() {
assert_eq!(
parse_csv_record("1,\"a,b\",\"c\"\"d\"").unwrap(),
["1", "a,b", "c\"d"]
);
assert_eq!(parse_scalar("42"), Value::Int(42));
assert_eq!(parse_scalar(""), Value::Null);
}
#[test]
fn migrate_rejects_unknown_duplicate_and_incomplete_options_before_io() {
let unknown = migrate_command(&[
"missing-source.pvdb".into(),
"missing-destination.pvdb".into(),
"--wat".into(),
])
.unwrap_err()
.to_string();
assert!(unknown.contains("unknown pv migrate option"));
let duplicate = migrate_command(&[
"missing-source.pvdb".into(),
"missing-destination.pvdb".into(),
"--json".into(),
"--json".into(),
])
.unwrap_err()
.to_string();
assert!(duplicate.contains("--json may be specified only once"));
let missing_backup = migrate_command(&[
"missing-source.pvdb".into(),
"missing-destination.pvdb".into(),
"--backup".into(),
])
.unwrap_err()
.to_string();
assert!(missing_backup.contains("--backup requires a path"));
}
#[test]
fn compact_rejects_unknown_duplicate_and_incomplete_options_before_io() {
let unknown = compact_command(&["missing-workspace".into(), "--wat".into()])
.unwrap_err()
.to_string();
assert!(unknown.contains("unknown pv compact option"));
let duplicate = compact_command(&[
"missing-workspace".into(),
"--max-pages".into(),
"1".into(),
"--max-pages".into(),
"2".into(),
])
.unwrap_err()
.to_string();
assert!(duplicate.contains("--max-pages may be specified only once"));
let missing_count = compact_command(&["missing-workspace".into(), "--max-pages".into()])
.unwrap_err()
.to_string();
assert!(missing_count.contains("--max-pages requires a non-negative integer"));
}
#[test]
fn csv_and_jsonl_import_export_round_trip() {
let temp = tempfile::tempdir().unwrap();
let csv = temp.path().join("users.csv");
std::fs::write(&csv, "id,name\n1,Ada\n2,\"Lin, Jr\"\n").unwrap();
let mut db = Database::open_memory();
assert_eq!(import_csv(&mut db, "users", &csv).unwrap(), 2);
let mut exported = Vec::new();
let QueryResult::Rows { columns, rows } =
db.query("SELECT * FROM users ORDER BY id").unwrap()
else {
panic!("expected rows")
};
write_jsonl(&mut exported, &columns, &rows).unwrap();
let text = String::from_utf8(exported).unwrap();
assert!(text.contains(r#"{"id":1,"name":"Ada"}"#));
assert!(text.contains(r#"{"id":2,"name":"Lin, Jr"}"#));
}
#[test]
fn history_reports_recent_snapshot_counts() {
let mut db = Database::open_memory();
db.query("CREATE TABLE events (id)").unwrap();
db.query("INSERT INTO events VALUES (1), (2)").unwrap();
let history = history_rows(&db, &["events".into()], 2).unwrap();
assert_eq!(history.len(), 2);
assert_eq!(history.last().unwrap().2, 2);
assert!(history[0].2 <= history[1].2);
}
#[test]
fn snapshot_diff_reports_deterministic_row_changes() {
let mut db = Database::open_memory();
db.query("CREATE TABLE tasks (id PRIMARY KEY, status)")
.unwrap();
db.query("INSERT INTO tasks VALUES (1, 'open'), (2, 'open')")
.unwrap();
let from = db.current_tx();
db.query("UPDATE tasks SET status = 'done' WHERE id = 1")
.unwrap();
db.query("DELETE FROM tasks WHERE id = 2").unwrap();
db.query("INSERT INTO tasks VALUES (3, 'open')").unwrap();
let to = db.current_tx();
let (columns, changes) = snapshot_diff(&db, "tasks", from, to).unwrap();
assert_eq!(columns, ["id", "status"]);
assert_eq!(
changes,
[
RowChange {
kind: ChangeKind::Removed,
row: vec![Value::Int(1), Value::Text("open".into())],
},
RowChange {
kind: ChangeKind::Removed,
row: vec![Value::Int(2), Value::Text("open".into())],
},
RowChange {
kind: ChangeKind::Added,
row: vec![Value::Int(1), Value::Text("done".into())],
},
RowChange {
kind: ChangeKind::Added,
row: vec![Value::Int(3), Value::Text("open".into())],
},
]
);
let mut csv = Vec::new();
write_diff_csv(&mut csv, &columns, &changes).unwrap();
assert_eq!(
String::from_utf8(csv).unwrap(),
"_change,id,status\nremoved,1,open\nremoved,2,open\nadded,1,done\nadded,3,open\n"
);
}
#[test]
fn snapshot_diff_preserves_duplicate_multiplicity() {
let mut db = Database::open_memory();
db.query("CREATE TABLE events (kind)").unwrap();
db.query("INSERT INTO events VALUES ('same'), ('same')")
.unwrap();
let from = db.current_tx();
db.query("INSERT INTO events VALUES ('same')").unwrap();
let to = db.current_tx();
let (_, changes) = snapshot_diff(&db, "events", from, to).unwrap();
assert_eq!(
changes,
[RowChange {
kind: ChangeKind::Added,
row: vec![Value::Text("same".into())],
}]
);
assert!(snapshot_diff(&db, "events", to, to).unwrap().1.is_empty());
}
#[test]
fn snapshot_diff_validates_transaction_range_and_json_shape() {
let mut db = Database::open_memory();
db.query("CREATE TABLE events (id, payload)").unwrap();
let from = db.current_tx();
db.query("INSERT INTO events VALUES (1, 'created')")
.unwrap();
let to = db.current_tx();
assert!(snapshot_diff(&db, "events", to, from)
.unwrap_err()
.to_string()
.contains("later than"));
assert!(snapshot_diff(&db, "events", from, to + 1)
.unwrap_err()
.to_string()
.contains("current transaction"));
let (columns, changes) = snapshot_diff(&db, "events", from, to).unwrap();
let mut jsonl = Vec::new();
write_diff_jsonl(&mut jsonl, &columns, &changes).unwrap();
assert_eq!(
String::from_utf8(jsonl).unwrap(),
"{\"change\":\"added\",\"row\":{\"id\":1,\"payload\":\"created\"}}\n"
);
}
}