Repository Pragmas

Repository pragmas are the primary API for embedding Graft in applications.

Lifecycle

PRAGMA graft_init;
PRAGMA graft_clone = 'fs:///srv/graft/app';
PRAGMA graft_clone = 'fs:///srv/graft/app feature/search';
PRAGMA graft_clone = '--branch feature/search fs:///srv/graft/app';

graft_init creates .graft/. graft_clone creates .graft/, configures origin, fetches a branch, sets upstream tracking, and materializes the database.

Status, Stage, Commit

PRAGMA graft_status;
PRAGMA graft_json_status;
PRAGMA graft_add;
PRAGMA graft_add = 'analytics.db';
PRAGMA graft_rm = 'analytics.db';
PRAGMA graft_commit = 'message';

Without an argument, graft_add stages the currently open database. With an argument, it stages a repo-relative SQLite database path.

History And Diff

PRAGMA graft_log;
PRAGMA graft_show = 'HEAD';
PRAGMA graft_json_show = 'HEAD';
PRAGMA graft_diff;
PRAGMA graft_diff = '--staged';
PRAGMA graft_diff = 'HEAD~1 HEAD -- app.db';
PRAGMA graft_json_diff = 'HEAD~1 HEAD -- app.db';

Repository diff arguments follow the CLI shape:

[--staged] [from] [to] [-- path]

Checkout, Restore, Reset

PRAGMA graft_checkout = 'HEAD~1';
PRAGMA graft_checkout = 'HEAD~1 -- app.db';
PRAGMA graft_checkout = '--force main';

PRAGMA graft_restore = '-- app.db';
PRAGMA graft_restore = '--source HEAD~1 -- app.db';
PRAGMA graft_restore = '--staged -- app.db';

PRAGMA graft_reset = 'HEAD~1';
PRAGMA graft_reset = '--soft HEAD~1';
PRAGMA graft_reset = '--mixed HEAD~1';
PRAGMA graft_reset = '--hard HEAD~1';

Export

PRAGMA graft_export = '--output app.inspect.db';
PRAGMA graft_export = '--source HEAD --output app.head.db';
PRAGMA graft_export = '--source HEAD~1 --output app.previous.db -- app.db';

graft_export writes a normal SQLite database file without moving HEAD, changing the index, or changing the current worktree Volume.

Argument shape:

[--source rev] --output output.db [-- path]

Without --source, it exports the currently opened database path. With --source, it exports the snapshot for path from that revision. If path is omitted, it defaults to the current database path.

Branches And Tags

PRAGMA graft_branch;
PRAGMA graft_branch = '--remote';
PRAGMA graft_branch = '--all';
PRAGMA graft_branch_create = 'feature/search';
PRAGMA graft_branch_create = 'feature/search main';
PRAGMA graft_branch_delete = 'feature/search';
PRAGMA graft_branch_delete = '--force feature/search';
PRAGMA graft_branch_rename = 'old new';
PRAGMA graft_branch_upstream = 'feature/search origin/main';
PRAGMA graft_branch_unset_upstream = 'feature/search';

PRAGMA graft_switch_branch = 'main';
PRAGMA graft_switch_create = 'feature/search main';

PRAGMA graft_tags;
PRAGMA graft_tag_create = 'v0.1 HEAD';
PRAGMA graft_tag_create = '--annotated v0.1 -- release notes';
PRAGMA graft_tag_delete = 'v0.1';

Remotes And Sync

PRAGMA graft_remote_add = 'origin fs:///srv/graft/app';
PRAGMA graft_remote_add = 'backup s3_compatible://my-bucket/prod?endpoint=https://account.r2.cloudflarestorage.com';
PRAGMA graft_remotes;
PRAGMA graft_remote_get_url = 'origin';
PRAGMA graft_remote_set_url = 'origin fs:///srv/graft/app-v2';
PRAGMA graft_remote_rename = 'origin upstream';
PRAGMA graft_remote_remove = 'upstream';
PRAGMA graft_remote_prune = 'origin';

PRAGMA graft_ls_remote = 'origin';
PRAGMA graft_fetch = 'origin main';
PRAGMA graft_fetch = '--all origin';
PRAGMA graft_pull = 'origin main';
PRAGMA graft_push = 'origin main';
PRAGMA graft_push = '--force origin main';
PRAGMA graft_push = '--all origin';

Merge And Conflict Resolution

PRAGMA graft_merge = 'feature/search';
PRAGMA graft_merge_abort;
PRAGMA graft_merge_continue = 'merge feature/search';
PRAGMA graft_conflicts;
PRAGMA graft_resolve = '--ours app.db';
PRAGMA graft_resolve = '--theirs app.db';

For the currently opened SQLite database, graft_merge can auto-merge non-conflicting row changes and stage the merged snapshot. Same-row, schema, add/delete, and opaque-table conflicts remain as conflict stages for graft_resolve or manual resolution.

The row-level merge planner is controlled by repository merge policy. See Merge Policy for semantic keys, schema resolvers, internal SQLite resolvers, and validation behavior.

Debug Pragmas

Caution

graft_debug_* pragmas are intentionally not the normal application API. They expose storage-layer details such as LSNs and page-level diagnostics.

Useful diagnostics:

PRAGMA graft_debug_log_lsn;
PRAGMA graft_debug_volume_diff = '2,4';
PRAGMA graft_debug_volume_diff = '2,4,rows';
PRAGMA graft_debug_volume_json_diff = '2,4,rows';