picovolt 2.2.0

Embedded SQL database with MVCC history and single-file deployment
Documentation
// Modified for PicoVolt 2.2.0 encryption/hybrid retrieval; see legal/COMPONENT-SCOPE-2.2.md.
// Modified for PicoVolt 2.1.0 retrieval, 2026-09-11. See legal/COMPONENT-SCOPE-2.1.md.
//! # PicoVolt (PVDB)
//!
//! A compact embedded SQL database with page-backed storage and MVCC history.
//! PicoVolt's Virtualization Layer Engine (VLE) shifts between a directory of
//! mutable append-only files (development mode) and an immutable,
//! memory-mappable single-file binary (`.pvdb`, production mode).
//!
//! ## Layout
//!
//! | Layer | Modules | Responsibility |
//! |-------|---------|----------------|
//! | core | [`core::types`], [`core::errors`], [`core::value`] | byte layouts, errors, value model |
//! | storage | [`storage::page`], [`storage::cas`], [`storage::compress`], [`storage::record`], [`storage::vle`] | pages, dedup, compression, serialization, file router |
//! | engine | [`engine::mvcc`], [`engine::wasm`], [`engine::query`], [`engine::compliance`] | snapshots, sandbox, SQL, optional host usage policies |
//! | surface | [`Database`] | dev/prod lifecycle, `query`, `bake` |
//!
//! ## Quick start
//!
//! Low-level layouts round-trip through explicit little-endian encoders:
//!
//! ```
//! use picovolt::{RecordEnvelope, RowPageHeader, FileHeader, MAGIC_BYTES};
//!
//! let env = RecordEnvelope::new(/* tx_inserted */ 1, /* prev_version */ 0);
//! assert!(env.is_active());
//! assert_eq!(RecordEnvelope::decode(&env.encode()).unwrap(), env);
//!
//! let page = RowPageHeader::new(0);
//! assert_eq!(RowPageHeader::decode(&page.encode()).unwrap(), page);
//!
//! let file = FileHeader::new(0x1000, 0x2000);
//! assert_eq!(&file.encode()[0..4], &MAGIC_BYTES);
//! ```
//!
//! The high-level surface opens a workspace, runs SQL (including `BEFORE tx`
//! time-travel), and bakes a production monolith:
//!
//! ```no_run
//! use picovolt::{Database, QueryResult};
//!
//! let mut db = Database::open_dev("./demo.pv")?;
//! db.query("CREATE TABLE users (id, name)")?;
//! db.query("INSERT INTO users VALUES (1, 'alice')")?;
//!
//! if let QueryResult::Rows { rows, .. } = db.query("SELECT * FROM users")? {
//!     assert_eq!(rows.len(), 1);
//! }
//!
//! db.bake("./app.pvdb")?;                  // compile to a single mmap'able file
//! let mut prod = Database::open_prod("./app.pvdb")?; // read-only
//! # Ok::<(), picovolt::PvError>(())
//! ```

mod cancel;
#[cfg(not(target_arch = "wasm32"))]
mod concurrent;
pub mod core;
/// Native authenticated snapshots and encrypted single-writer vaults.
#[cfg(all(feature = "encryption", not(target_arch = "wasm32")))]
pub mod encryption;
pub mod engine;
#[cfg(feature = "enterprise")]
pub mod enterprise;
pub mod journal;
#[cfg(any(feature = "full-text", feature = "vector-search"))]
pub mod retrieval;
#[cfg(feature = "full-text")]
pub mod search;
pub mod storage;
#[cfg(feature = "vector-search")]
pub mod vector;
pub use journal::{
    BlobChange, ChangeCommit, ChangeSink, CommitLogOptions, CommitLogStatus, PageChange,
    SnapshotCheckpoint, COMMIT_LOG_DIR,
};

/// History-preserving baked-image format migration.
pub mod upgrade;

mod db;

/// Best-effort import of a SQL dump (see [`Database::import_sql`]).
pub mod migrate;

/// Shared query-result JSON serialization for the language bindings.
#[cfg(any(feature = "wasm", feature = "capi"))]
mod json;

/// JavaScript / npm bindings (enabled by the `wasm` feature).
#[cfg(feature = "wasm")]
pub mod wasm_api;

/// C ABI for native FFI bindings such as Go (cgo) and Python (ctypes), enabled
/// by the `capi` feature.
#[cfg(feature = "capi")]
pub mod ffi;

#[doc(inline)]
pub use crate::cancel::CancellationToken;
#[cfg(not(target_arch = "wasm32"))]
#[doc(inline)]
pub use crate::concurrent::{
    ReadTransaction, RequestOptions, SharedDatabase, SharedDatabaseOptions, WriteTransaction,
    DEFAULT_SHARED_QUEUE_CAPACITY,
};
#[doc(inline)]
pub use crate::core::errors::{ComplianceError, PvError, Result};
#[doc(inline)]
pub use crate::core::types::*;
#[doc(inline)]
pub use crate::core::value::{Row, Value};
#[doc(inline)]
pub use crate::db::{
    pv_bake, pv_open_dev, pv_open_prod, BufferPoolStats, CasStats, CompactionReport,
    CompressionStats, Database, DatabaseStats, Durability, IndexStats, PreparedStatement,
    QueryLimits, QueryResult, TableStats, MANIFEST_FILE, TRANSACTION_BACKUP_DIR,
    TRANSACTION_LOCK_FILE, TRANSACTION_MARKER_FILE,
};
#[doc(inline)]
pub use crate::engine::compliance::{ComplianceMonitor, RuntimeMetrics};
#[doc(inline)]
pub use crate::engine::interp::{Interpreter, PvModule};
#[doc(inline)]
pub use crate::engine::mvcc::{Snapshot, TxManager};
#[doc(inline)]
pub use crate::engine::wasm::{WasmExec, WasmModule, WasmRuntime};
#[cfg(feature = "enterprise")]
#[doc(inline)]
pub use crate::enterprise::{
    AuditEvent, AuditEventKind, AuditSink, EnterpriseCapabilities, EnterpriseConfig,
    EnterpriseStatus, AUDIT_EVENT_SCHEMA_VERSION, ENTERPRISE_STATUS_SCHEMA_VERSION,
};
#[doc(inline)]
pub use crate::migrate::ImportReport;
#[doc(inline)]
pub use crate::upgrade::{
    migrate_file, plan_file_migration, MigrationOptions, MigrationPlan, MigrationReport,
};