XDB

What is XDB?

XDB stores JSON records in named collections using SQLite. Its Rust library provides record operations, transactions, import and export, and the state needed by its native peer protocol. Tauri commands expose that functionality to a desktop application, while the separate @xdb/react package provides convenient hooks for a React interface.

Local persistence is the foundation. A record can be written without a network connection, and the host can decide whether synchronisation is appropriate. XDB’s native peer feature is experimental and opt-in. It is not a hosted account service or a replacement for application-level authentication.

A record model with predictable write boundaries

Records include an identifier, collection, JSON data, creation and update timestamps, and deletion state. Newly created records use UUIDs. An update shallow-merges object fields, while a non-object value replaces the payload. Ordinary collection reads hide deleted records; lower-level reads can expose tombstones when needed.

Transactions coordinate SQLite changes with the cached CRDT state. Nested work uses savepoints, so an inner failure can be rolled back without leaving one side committed and the other stale. Bulk imports and updates return success only after their transaction has committed.

• Read and write JSON records in named collections.
• Group changes into transactions and nested savepoints.
• Keep app-scoped records in separate native SQLite files.
• Export consistent database snapshots, including committed WAL data.
• Observe mutation, import and synchronisation events from the host.

What native peer synchronisation does and does not mean

The native development transport uses libp2p discovery, GossipSub and Yrs documents. The current wire protocol supports the default database scope and is intended for a trusted local network. Opening the database through the storage API does not itself start a peer network; the host must deliberately enable the supported network path.

Concurrent changes to different records can merge. Changes to the same record resolve at whole-record granularity, because a CRDT map entry contains a serialised record. That is not field-by-field collaborative editing. Applications that need collaborative text or independently merged fields need a different data representation or explicit conflict handling.

Retained state and reconciliation help a peer recover changes when it reconnects. Status reports describe actual publishes, applied or rejected updates and reconciliation activity rather than making a blanket claim that everything is synchronised. Network partitions, scope and the peer trust model still matter.

Backups and restores are data operations, not just files

A local reset, a replicated deletion and an authoritative restore have different meanings. Removing local collection data can allow peers to repopulate it later. Replicated deletion uses tombstones. Authoritative resets use epochs so a returning peer with older state cannot silently restore data that was intentionally replaced.

Database imports offer local, fork and replace scopes. A local restore pauses synchronisation, a fork creates an isolated namespace, and a replacement coordinates authoritative reset state with the imported data. Interrupted restores use a recovery journal and require an explicit resolution when safe automatic continuation is not possible.

This is why a backup needs an operating policy. Decide whether the restored database should rejoin peers, remain isolated or replace their shared state. Keep the recovery path and the data snapshot together when testing a restore procedure.

XDB in the wider F2i stack

SoftN’s desktop runtime and Rust server use this repository’s Rust crate. SoftN’s browser runtime has a separate TypeScript XDB service and its own browser storage and synchronisation behaviour. Native command adapters connect those surfaces when the host supports them, but browser code does not become a libp2p peer simply because it uses an XDB-named API.

FormLogic’s connected business records use FormLogic’s own backend storage. Aokie has its own native call and message persistence. OAIY and ZIPP do not directly depend on this XDB crate: SoftN supplies the database bridge to app logic. Keeping those responsibilities separate avoids assuming that every record across the ecosystem shares one replication mechanism.

Begin with storage, then decide whether to synchronise

Run the React/Tauri demo to explore CRUD, status and database import/export. A browser-only frontend is not sufficient for the native database commands; use the Tauri host. Rust servers can depend on the crate without the Tauri integration when they only need storage and host-controlled synchronisation.

Use stable app identifiers and review sanitisation behaviour. A storage namespace is not a user identity or an access-control boundary. Before enabling native peer sync, read the networking and restore policy and test concurrent writes, disconnect/rejoin and backup recovery with non-sensitive data.