Skip to content
Graft

Project Status

Graft is an experimental project. This documentation targets the v0.8.0 release and focuses on app-state versioning for SQLite-backed apps: SQLite database snapshots, app-owned files, row-aware diffs, merge support, and remote sync.

Features that exist only on the development branch are not part of the v0.8.0 documentation unless a page labels them as unreleased.

Available Today

Section titled “Available Today”
  • CLI workflows for init, clone, sql, status, audit, gc, ls-files, payload, config, add, rm, commit, log, show, diff, checkout, restore, export, reset, branch, switch, tag, merge, conflicts, resolve, remote, ls-remote, fetch, pull, and push.
  • A SQLite extension that provides the optional Graft VFS plus version and low-level graft_debug_* diagnostics.
  • Repository-local state under .graft/.
  • Multiple tracked SQLite database paths in one worktree.
  • Text and binary file artifacts in the same commit tree as SQLite snapshots.
  • External payload storage for binary files and configured paths.
  • Row-level diff output for ordinary rowid tables and declared-primary-key WITHOUT ROWID tables, including STRICT and composite-key schemas.
  • Row-aware merge planning and per-row resolution for those supported SQLite changes.
  • JSON output for app-facing status, diff, conflict, payload, config, and sync UIs.
  • Remotes using fs://, s3://, s3_compatible://, and graft+http(s)://.
  • An HTTP remote client for services that implement the Graft HTTP remote protocol.

Stability Boundaries

Section titled “Stability Boundaries”

Treat repository-mode CLI commands, config keys, and JSON output as the intended external surfaces. They may still change while the project is experimental, but they are the surfaces this documentation is organized around.

Treat these as implementation details:

  • storage LSNs
  • page and segment layout
  • debug pragmas
  • object serialization internals
  • internal Rust module boundaries

The internals pages document those details for contributors and advanced debugging, not as product-level API guarantees.

Compatibility Notes

Section titled “Compatibility Notes”

Graft works alongside ordinary SQLite tooling by using physical worktree files and materializing committed snapshots back to those paths. After an external tool commits a transaction, stage the physical path with graft add. The staging snapshot includes committed WAL frames, so a manual checkpoint is not required.

Terminal window
sqlite3 data.sqlite "INSERT INTO notes(body) VALUES ('hello');"
graft add data.sqlite

Close database connections before branch, checkout, restore, or reset operations that replace the file. Graft refuses to replace a database under an active writer.

Release Artifacts

Section titled “Release Artifacts”

Prebuilt CLI and SQLite extension archives are published with the v0.8.0 GitHub release.

The repository is an experimental fork of orbitinghail/graft. The upstream project is a transactional storage engine for lazy, partial data replication on object storage. This fork applies that foundation to SQLite-backed app-state versioning.