octra-sqlite

Real SQLite inside an Octra Circle.

octra-sqlite runs the SQLite C engine inside an Octra wasm_v1 Circle. It gives you a SQLite-shaped CLI and a small Rust client for live Circle state: query public databases without a wallet, create sealed or public-read databases with an Octra wallet, and verify what was deployed.

If you're new to Octra, start with the official Octra docs and Circles guide. In this project, a Circle is the Octra-hosted WASM environment that owns the SQLite pages and executes the SQLite engine.

• Real SQLite: SQL is executed by the bundled SQLite C amalgamation.
• Octra-native writes: state-changing SQL is owner-signed through OSW1 owner write intent.
• Public when you choose: public-read databases can be queried without a wallet, while sealed databases remain the default.
• Verifiable deployment: the bundled WASM, rebuild inputs, audit script, hashes, and devnet proof metadata are published with each release.

CLI Quick Start

You need Rust/Cargo 1.88+ from a current Rust toolchain. If cargo is missing, install Rust with rustup; distro packages such as apt install cargo may be too old. The Circle WASM is bundled; no local WASM toolchain is required.

cargo install octra-sqlite --locked

Read a public database immediately, no wallet required:

octra-sqlite 'oct://devnet/octQfYK2fE9RvR9kfj8FJfMBQw1e4EzfHB8Q5Z9J2DCnRBQ' \
  "select id, name from artist order by id;"

Open the same database in the interactive sqlite> shell:

octra-sqlite open 'oct://devnet/octQfYK2fE9RvR9kfj8FJfMBQw1e4EzfHB8Q5Z9J2DCnRBQ'

Create a database when you have a funded Octra wallet:

octra-sqlite setup
octra-sqlite new art < examples/artists.sql
octra-sqlite status art --ready
octra-sqlite art "select * from artist order by name;"

setup walks you through wallet and network defaults; see Wallets for wallet options and docs/headless.md for scripted setup.

Rust Client Quick Start

[dependencies]
octra-sqlite = "0.5"

use octra_sqlite::{Client, Result};

fn main() -> Result<()> {
    let client = Client::default();
    let db = client.database(
        "oct://devnet/octQfYK2fE9RvR9kfj8FJfMBQw1e4EzfHB8Q5Z9J2DCnRBQ",
    )?;
    let rows = db.query("select id, name from artist order by id;")?;
    println!("{} rows", rows.row_count);
    Ok(())
}

The high-level Rust path is deliberately small: Client -> Database -> query/execute. Use client::raw only for lower-level adapter plumbing that needs to reproduce CLI-style signed Octra RPC flows.

Rust API Surface

The crate root exports the first-story API: Client, ClientOptions, Database, QueryResult, ExecuteResult, SubmittedTransaction, AuthInfo, ProgramInfo, ReadMode, Value, Error, ErrorKind, and Result.

Use Client::default() for config-free public reads, Client::from_default_config() for local CLI config, and Client::with_options(...) when code needs explicit target, wallet, RPC, caller, or key-material overrides. Lower-level transport/session helpers live under octra_sqlite::client and octra_sqlite::client::raw. See docs.rs for the authoritative Rust API reference.

Writes And Read Modes

Databases are sealed by default. Sealed databases use signed Octra view auth for reads and owner-signed OSW1 calls for writes.

Public-read databases are explicit:

octra-sqlite new public_art --read-mode public --schema examples/artists.sql

Public-read SQL queries use unsigned octra_circleView; anyone can query the public data. Writes remain owner-signed OSW1 calls in both read modes. Raw Circle targets detect the Octra read surface automatically; use ?read_mode=sealed or ?read_mode=public only when you need an explicit override.

Wallets

Public-read queries do not need a wallet. Sealed reads and all writes require a configured Octra wallet because reads use signed Octra view auth and writes are owner-signed.

octra-sqlite setup
octra-sqlite wallet status
octra-sqlite wallet attach ./wallet.json
printf '%s' "$OCTRA_PRIVATE_KEY_B64" | octra-sqlite wallet import --stdin --output ./wallet.json

Supported wallet inputs are an official Octra wallet-generator wallet.json from wallet.octra.org, an existing plaintext wallet JSON, or a private key pasted/imported through the CLI. WebCLI .oct files are encrypted/PIN-protected and are not imported directly; use the official wallet.json, attach plaintext wallet JSON, or import the private key.

Verifiability

The crate ships circle/wasm/octra_sqlite_circle.wasm so users do not need a local WASM toolchain. scripts/audit-wasm.sh checks the Circle import/export surface, docs/toolchain.md records the rebuild inputs, and release manifests publish the bundled WASM hash plus live devnet proof metadata.

The 0.5.2 crate uses the same bundled Circle WASM as 0.5.0. The current release manifest is release/octra-sqlite-0.5.2.json.

Rust CLI/client -> Octra RPC -> Circle wasm_v1
                                  |
                                  v
                   SQLite C engine -> VFS -> Octra page storage

The consensus surface is intentionally small: SQLite runs SQL, the VFS stores SQLite pages in Octra storage, and the Rust client handles signing, rendering, backup, restore, and local developer experience.

Stability

MSRV is Rust 1.88. While the crate is 0.x, the Rust API may change in minor versions. CLI JSON envelopes, commands --json, release manifests, and the OSR1/OSW1 wire formats are treated as stable automation surfaces and changed carefully.

octra-sqlite is still alpha software for Octra testing. Do not store secrets, production records, financial records, or irreplaceable data in alpha databases.

CLI Commands

In commands below, DATABASE can be a saved database name or a raw oct:// URI.

The same public command surface is documented in docs/public-surface.md and emitted in machine form by octra-sqlite commands --json.

sqlite> Shell

Run octra-sqlite DATABASE or octra-sqlite open DATABASE to enter the shell.

sqlite> select id, name
   ...> from artist
   ...> order by name;
sqlite> .tables
sqlite> .quit

sqlite> is ready for a new SQL statement or dot command. ...> is waiting for the rest of a multiline SQL statement. SQL runs when it ends with ;. Dot commands run immediately.

Backup And Restore

octra-sqlite art ".backup main art.sqlite"
sqlite3 art.sqlite "pragma integrity_check;"

octra-sqlite art ".dump" > art.sql
octra-sqlite new art_copy
octra-sqlite restore art_copy --file art.sql

Local sqlite3 is optional. It is used only for exported-file integrity checks and local snapshot rendering commands such as .dump and .fullschema. The octra-sqlite commands talk to the Octra Circle. See docs/operations.md for restore and backfill guidance.

Reference

• API docs
• Examples
• Release manifests
• Public surface
• Headless setup
• JSON output
• Operations
• Storage model
• Toolchain and builds
• OSR1 typed results
• OSW1 owner write intent

License, Contributing, Security

octra-sqlite is licensed under the MIT license. See CONTRIBUTING.md for contribution guidance and SECURITY.md for the current security policy.