跳转到内容
Graft

SQLite 扩展快速开始

大多数应用应使用普通 SQLite worktree file 和 Graft CLI。只有明确希望 SQLite 打开 期间由 Graft Volume 保存 live pages 时，才需要 SQLite extension。

extension 注册 vfs=graft，并提供 version 和低层 graft_debug_* PRAGMA。 status、add、commit、branch、merge 和 sync 等 repository command 不再是 SQLite PRAGMA，统一通过 CLI 执行。

live VFS 写入路径要求 SQLite page_size=4096，因为一个 live SQLite page 会直接 映射到一个 Graft page。物理 worktree staging 没有这个限制，支持例如 8 KiB page size 的数据库。

初始化 Repository

Section titled “初始化 Repository”

先从 shell 创建 repository：

Terminal window
mkdir app-state
cd app-state
graft init

通过 Graft VFS 打开数据库

Section titled “通过 Graft VFS 打开数据库”

在 SQLite shell 中：

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

绝对路径仍映射为 repository-relative path data.sqlite，但 live pages 由 repository 的 Graft storage 支撑，而不是普通 worktree file。

写入和提交

Section titled “写入和提交”

  1. 通过 VFS connection 执行普通 SQL。

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

  2. 关闭 connection，再通过 CLI 查看和 stage。

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

  3. 通过 CLI 比较 repository revision。

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

Extension Diagnostics

Section titled “Extension Diagnostics”

生产 extension 的 PRAGMA 表面刻意保持很小：

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

这些命令检查当前 VFS Volume，不读取或修改 repository branch、index、commit、remote 或 merge state。完整列表见 VFS PRAGMA。

默认物理模式

Section titled “默认物理模式”

如果不需要 live Volume storage，就跳过 extension 并正常打开 data.sqlite。 graft add 会取得一致 SQLite backup、包含 committed WAL frames，并且只存储相对 当前 staged 或 committed snapshot 发生变化的 page。这是大多数应用的推荐集成方式。