SQLite Extension

The SQLite extension is the main integration surface for applications. It registers a Graft VFS, stores SQLite pages in Graft storage, and exposes repository operations through PRAGMA graft_*.

Open A Database Through Graft

In the SQLite shell:

.load ./libgraft_ext
.open "file:/path/to/project/app.db?vfs=graft"

Then initialize the project:

PRAGMA graft_init;

After initialization, repository data is stored under:

/path/to/project/.graft/

Basic Workflow

Write normal SQLite data.

CREATE TABLE users(id INTEGER PRIMARY KEY, name TEXT NOT NULL);
INSERT INTO users(name) VALUES ('Alice');

Inspect repository status.
```
PRAGMA graft_status;
```
Stage the current database snapshot.
```
PRAGMA graft_add;
```
Commit the staged snapshot.
```
PRAGMA graft_commit = 'seed users';
```

Compare revisions.

PRAGMA graft_diff = 'HEAD~1 HEAD -- app.db';
PRAGMA graft_json_diff = 'HEAD~1 HEAD -- app.db';

Repository Mode Is Path-Based

The database path is part of the repository identity. Opening /project/app.db through the Graft VFS makes app.db the worktree path for that database inside /project; the ordinary SQLite file only exists when you explicitly import or export one.

This is why repository mode no longer depends on environment variables for normal use. Configuration, refs, objects, and local storage live under .graft/.

Multiple Databases

A repository can track more than one SQLite database file:

project/
  app.db
  analytics.db
  .graft/

Stage a specific database path:

PRAGMA graft_add = 'analytics.db';
PRAGMA graft_commit = 'track analytics database';

Application Integration

Any language that can execute SQLite SQL can call the same pragmas:

PRAGMA graft_status;
PRAGMA graft_add;
PRAGMA graft_commit = 'commit from app';