PicoVolt for Python

For 2.0, see the interface quickstart for batching, persistence and diagnostics. Use matching 2.0 artifacts.

Python bindings for the PicoVolt embedded database engine, via its C ABI and ctypes. Released platform wheels bundle the native library, so installing from PyPI does not require a Rust or C compiler.

Like the engine itself, this is for embedded use (single writer, SQL with MVCC time-travel, compile-to-.pvdb), not a drop-in for a concurrent server's primary database.

Install

Platform wheels bundle the native library, so released builds install without a Rust compiler. The compatibility floor is Python 3.9, but production deployments should use a Python release that still receives upstream security fixes:

python -m pip install picovolt

Build the shared library from the repository root:

cargo build --release --features capi

That produces target/release/libpicovolt.so (Linux), target/release/libpicovolt.dylib (macOS), or target/release/picovolt.dll (Windows). When you run from a checkout, the wrapper finds it in target/release automatically. Otherwise set PICOVOLT_LIB to the file:

export PICOVOLT_LIB=/path/to/libpicovolt.so

Usage

from picovolt import Database

with Database.open_memory() as db:
    db.query("CREATE TABLE users (id, name)")
    db.query("INSERT INTO users VALUES (1, 'alice')")
    print(db.query("SELECT * FROM users"))
    # {'columns': ['id', 'name'], 'rows': [[1, 'alice']]}

query returns the already-parsed result (a dict): {"columns": [...], "rows": [[...]]} for a SELECT, {"mutated": n} for a mutation, or {"done": True} otherwise. Other methods: open_dev, open_prod, from_bytes, export, begin, commit, rollback, in_transaction, current_tx, and the module-level version(). A PEP 249 adapter is available as picovolt.dbapi2.

For SQL executed repeatedly, prepare it once. The wrapper caches the SQL text and positional-parameter count, validates arity before each execution, and passes values through the same injection-safe binder as query:

with db.prepare("INSERT INTO users VALUES (?, ?)") as insert:
    print(insert.parameter_count)  # 2
    insert.execute((1, "Ada"))
    insert.execute((2, "Lin"))

Preparation validates SQL and retains a native statement handle. Close the statement (or use its context manager) before closing the database. A statement does not own or close its database, and executing it after either handle has been closed raises PicoVoltError.

Run the demo:

python example.py

Release wheels are built for Linux x86-64, macOS universal2, and Windows x86-64 by GitHub Actions. Source checkouts and other architectures can instead use PICOVOLT_LIB to select a locally built library.