SQLite Extension Quickstart

Most applications should use ordinary SQLite worktree files and the Graft CLI. The SQLite extension is for applications that deliberately want SQLite pages to live in a Graft Volume while the database is open.

The extension registers vfs=graft and exposes version and low-level graft_debug_* PRAGMAs. Repository commands such as status, add, commit, branch, merge, and sync are not SQLite PRAGMAs; run them through the CLI.

The live VFS write path requires SQLite page_size=4096, because each live SQLite page maps directly to one Graft page. Physical worktree staging does not have this requirement and supports databases with page sizes such as 8 KiB.

Choose one write path

Do not write the same logical database through both the platform file VFS and the Graft VFS. Close live SQLite connections before branch operations that replace or rebind database state.

Initialize The Repository

Create the repository from a shell:

mkdir app-state
cd app-state
graft init

Open A Database Through The Graft VFS

In the SQLite shell:

.load ./libgraft_ext
.open "file:/path/to/app-state/data.sqlite?vfs=graft"

The absolute path maps to the repository-relative path data.sqlite, but its live pages are backed by the repository’s Graft storage rather than a normal worktree file.

Write And Commit

1. Write normal SQL through the VFS connection.

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

2. Close the connection, then inspect and stage through the CLI.

   graft status
   graft add data.sqlite
   graft commit -m "seed users"

3. Compare repository revisions through the CLI.

   graft diff --rows HEAD~1 HEAD data.sqlite
   graft diff --json --rows HEAD~1 HEAD data.sqlite

Extension Diagnostics

The production extension keeps a deliberately small PRAGMA surface:

PRAGMA graft_version;
PRAGMA graft_debug_volume_info;
PRAGMA graft_debug_volume_json_info;
PRAGMA graft_debug_log_lsn;

These commands inspect the open VFS Volume. They do not read or mutate repository branches, the index, commits, remotes, or merge state. See VFS PRAGMAs for the complete diagnostic surface.

Default Physical Mode

If live Volume storage is not required, skip the extension and open data.sqlite normally. graft add will take a consistent SQLite backup, include committed WAL frames, and store only pages that changed from the current staged or committed snapshot. This is the recommended integration for most applications.