Skip to content
eidos-spacePublic

About

Git-style version control for SQLite

Resources

Contributing

Stars

3 stars

Watchers

1 watching

Forks

Latest commit

 

History

1,568 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Graft

Version history for SQLite databases and application files.

Try the Playground · Documentation · Releases · 简体中文

Graft records versions of your application's SQLite databases and related files. You can inspect row changes, restore a recorded state, combine supported branch edits, and send history to a remote. Your application keeps using ordinary SQLite connections and file APIs.

What gets recorded?

Suppose a note in app.sqlite refers to attachments/report.pdf, and settings.json controls how the application displays it. You can record their selected versions in one commit, then return to that recorded combination.

Graft understands supported SQLite content:

  • Consistent snapshots, including committed WAL frames
  • Content-addressed chunks that reuse unchanged SQLite content across versions
  • Schema-, table-, and row-level diffs and merges
  • Git-like commits, branches, tags, restore, and remote sync
app-data/
├── app.sqlite
├── settings.json
└── attachments/
    └── report.pdf

A shared commit does not create a transaction across these files. Coordinate application writes when the files must represent the same checkpoint.

Graft uses a Git-like workflow with its own repository and remote formats.

Try Graft

The Graft Playground runs the browser CLI in an OPFS worktree. Try local commits, branches, row diffs, and conflicts without installing anything. Native remote synchronization is unavailable in the browser host.

Install the latest release on macOS or Linux:

curl -fsSL https://graft.eidos.space/install.sh | sh

Create a repository and save a SQLite database:

mkdir graft-demo
cd graft-demo

graft init
graft sql --db app.sqlite \
  "CREATE TABLE notes(id INTEGER PRIMARY KEY, body TEXT NOT NULL);"
graft sql --db app.sqlite \
  "INSERT INTO notes(body) VALUES ('first note');"
graft add app.sqlite
graft commit -m "Save initial state"
graft log
graft sql --db app.sqlite "SELECT id, body FROM notes;"

The query returns the first note. The log contains the recorded version.

Continue with the CLI quickstart.

Open an existing repository in the local browser viewer:

graft .

The React viewer keeps file contents and diffs beside an explorer with All files, Changes, and History. It previews text changes and SQLite row changes, browses current database tables, and can save small UTF-8 text files. HTML and SVG use the source viewer. Worktree raster images, audio, video, and PDF files have dedicated previews. Saving changes the worktree; use the CLI to stage and commit. The server runs on loopback until Ctrl+C. Use graft ui . --no-open --port 4178 to choose a port and print the URL without opening a browser.

Choose an Integration

Integration Use it for
CLI Evaluation, scripts, agents, and one-shot commands
Structured JSON output Stable application and automation boundaries
Node.js SDK Long-lived, in-process repository sessions
Docker self-hosted server Personal server with Lite discovery, repository management and encrypted sync
Remote service packages Hosting the Graft HTTP remote protocol

Install the Node.js SDK with:

pnpm add @eidos.space/graft

Who Uses Graft?

Eidos Lite

Eidos Lite is a local-first desktop app for .eidos relational spreadsheets and ordinary files. It uses Graft to:

  • Record an entire local workspace as one version
  • Show file changes and row-level SQLite changes before saving
  • Inspect and restore earlier versions without rewriting history
  • Synchronize workspace history through optional Eidos Sync

The integration is open source in the Eidos repository.

Using Graft in a product? Open a pull request to add it here.

Saving, staging, and recording

Action What changes
SQLite transaction or file write Current application files in the worktree
graft add Selected snapshots and file bytes in the index (staging area)
graft commit Local repository history, using staged content
graft push Remote history, using recorded commits
Restore or switch Worktree files, using recorded content

If you insert a note after add, commit still records the earlier snapshot. The new note remains an unstaged worktree change. Push does not upload it as a new version until you stage and commit it.

A repository stores its history in .graft/ beside the normal worktree. Applications keep using their existing SQLite library and file APIs.

Staging captures committed WAL content without a manual checkpoint. Restore and branch switching can replace database files; close affected application connections before those operations.

The architecture guide explains these boundaries. Its lab lets you predict a result, run the command, and check it with a SQL query.

Project Status

Graft is experimental. The CLI, structured output, Node.js SDK, and remote protocol are supported integration surfaces. Storage layouts and internal Rust modules remain implementation details.

Graft complements SQLite transactions; it does not replace application authorization, real-time replication, or Git source control.

Development

See CONTRIBUTING.md for the full workflow.

cargo check --workspace --all-targets
just test

pnpm check:remote
pnpm test:remote

The implementation-aligned specifications live in docs/specs.

Lineage

Graft began as a fork of orbitinghail/graft. Its original transactional storage engine now powers this project's SQLite storage layer. This repository is independently maintained and is no longer a GitHub fork.

License

Licensed under either the Apache License 2.0 or the MIT License, at your option.

About

Git-style version control for SQLite

Resources

Contributing

Stars

3 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages