Dolt 快速入门

‍‍‌> 目标：用最短的命令闭环体验 Dolt 的「Git for Data」核心工作流——初始化仓库、建表写入、提交、开分支、合并、看差异；全文命令与回显均在 Ubuntu 22.04 LTS（x86_64）+ Dolt v2.5.0 真实环境逐条跑通，数据目录为 /opt/data/dolt/demo。安装步骤见《Dolt 安装部署指南》，本文假设 dolt 命令可用。

一、环境信息

本文所有命令与回显所依赖的实测环境：

操作系统：Ubuntu 22.04 LTS（x86_64）
Dolt：v2.5.0（官方 linux-amd64 tarball 安装，dolt version 实测回显 2.5.0）
实验数据目录：/opt/data/dolt/demo（空目录新建）
全局配置：user.name=admin、user.email=admin@quzuo.net（dolt config --global 设置，见下文）
前置阅读：dolt 二进制尚未安装时，请先看《Dolt 安装部署指南》完成安装

二、前置条件

2.1 验证 dolt 命令可用

先确认二进制已在 PATH 中且版本正确：

which dolt && dolt version

实测回显：

/usr/local/bin/dolt
dolt version 2.5.0

⚠️ 注意：dolt version 可能伴随一行 Warning: unable to query latest released Dolt version，这是它联网检查新版本失败（离线或网络受限环境常见）的提示，不影响任何本地功能，v2.5.0 版本号照常输出。

2.2 设置全局用户信息

Dolt 的提交（commit）必须记录作者，首次使用前需配置用户名与邮箱（语义与 git config --global 一致）：

dolt config --global --add user.email "admin@quzuo.net"
dolt config --global --add user.name "admin"
dolt config --global --list

实测回显：

user.email = admin@quzuo.net
user.name = admin

2.3 创建并初始化数据仓库

Dolt 的「数据库」就是一个含 .dolt/ 目录的文件夹。新建空目录并初始化：

mkdir -p /opt/data/dolt/demo && cd /opt/data/dolt/demo
dolt init
dolt status
ls -la .dolt/

实测回显：

Successfully initialized dolt data repository.
On branch main
nothing to commit, working tree clean

.dolt/ 目录关键内容（实测列表节选）：

config.json        # 仓库级配置
noms/              # 内容寻址存储层（数据与提交图落盘处）
repo_state.json    # 当前分支、HEAD 等引用状态
stats/             # 统计信息

💡 说明：dolt init 默认初始分支为 main，dolt status 语义与 git status 完全一致——此刻工作区干净、没有任何待提交变更。

三、五分钟最短闭环

本节按「建表 → 提交 → 分支 → 修改 → 合并 → 差异」的顺序走完 Dolt 的核心闭环，每一步都有真实回显。

3.1 建表并插入数据

用 dolt sql -q 执行单条 SQL（执行完即退出，适合脚本化）：

dolt sql -q "create table products (id int primary key, name varchar(100) not null, price decimal(10,2), stock int default 0)"
dolt sql -q "insert into products values (1, 'Keyboard', 199.00, 50), (2, 'Mouse', 89.50, 120), (3, 'Monitor', 1299.00, 20)"
dolt sql -q "select * from products"

实测回显：

+----+----------+---------+-------+
| id | name     | price   | stock |
+----+----------+---------+-------+
| 1  | Keyboard | 199.00  | 50    |
| 2  | Mouse    | 89.50   | 120   |
| 3  | Monitor  | 1299.00 | 20    |
+----+----------+---------+-------+

3.2 暂存并提交

数据现在只存在于「工作区」。与 Git 相同，先 add 暂存、再 commit 提交，schema 与数据一起进入版本库：

dolt status
dolt add products
dolt status
dolt commit -m "初始库存表：新增 products 表与 3 条基础数据"

实测回显（两次 status 分别展示未暂存与已暂存状态）：

On branch main
Untracked tables:
  (use "dolt add <table>" to include in what will be committed)
        new table:        products

On branch main
Changes to be committed:
  (use "dolt reset <table>..." to unstage)
        new table:        products

commit 53lb9ufgdfk6m60dob20n13imvpsqbpo (HEAD -> main)
Author: admin <admin@quzuo.net>
Date:  Sun Oct 18 11:10:27 +0800 2026

        初始库存表：新增 products 表与 3 条基础数据

提交哈希形如 53lb9ufgdfk6m60dob20n13imvpsqbpo，是内容寻址生成的固定长度字符串（比 Git 的 40 位十六进制更长，Dolt 使用 base32 编码的块哈希），可用它做后续一切版本引用。

3.3 开分支并修改数据

建一条 price-adjust 分支，在其上给商品打八折：

dolt checkout -b price-adjust
dolt branch
dolt sql -q "update products set price = price * 0.8 where id in (1,2)"
dolt sql -q "select id, name, price from products"
dolt add products
dolt commit -m "促销：Keyboard 与 Mouse 打八折"

实测回显：

Switched to branch 'price-adjust'
  main
* price-adjust

+----+----------+---------+
| id | name     | price   |
+----+----------+---------+
| 1  | Keyboard | 159.20  |
| 2  | Mouse    | 71.60   |
| 3  | Monitor  | 1299.00 |
+----+----------+---------+

commit o93jcrjiirvurhsd92dtsi9cv5kfoctl (HEAD -> price-adjust)
Author: admin <admin@quzuo.net>
Date:  Sun Oct 18 11:10:38 +0800 2026

        促销：Keyboard 与 Mouse 打八折

此刻切回 main 会发现价格仍是原值——分支上的修改对其他分支不可见，这就是「数据分支」的意义。

3.4 分支间 diff

直接对比两个分支的数据差异：

dolt diff main price-adjust

实测回显：

diff --dolt a/products b/products
--- a/products
+++ b/products
+---+----+----------+--------+-------+
|   | id | name     | price  | stock |
+---+----+----------+--------+-------+
| < | 1  | Keyboard | 199.00 | 50    |
| > | 1  | Keyboard | 159.20 | 50    |
| < | 2  | Mouse    | 89.50  | 120   |
| > | 2  | Mouse    | 71.60  | 120   |
+---+----+----------+--------+-------+

💡 说明：< 表示左侧（main）的行值，> 表示右侧（price-adjust）的行值；主键相同的行按对齐展示，一眼可见改动前后。

3.5 合并回主干

切回 main 验证数据未变，再执行合并：

dolt checkout main
dolt sql -q "select * from products"
dolt merge price-adjust
dolt sql -q "select * from products"
dolt log -n 2

实测回显：

Switched to branch 'main'

+----+----------+---------+-------+
| id | name     | price   | stock |
+----+----------+---------+-------+
| 1  | Keyboard | 199.00  | 50    |
| 2  | Mouse    | 89.50   | 120   |
| 3  | Monitor  | 1299.00 | 20    |
+----+----------+---------+-------+

Fast-forward
Updating o93jcrjiirvurhsd92dtsi9cv5kfoctl..o93jcrjiirvurhsd92dtsi9cv5kfoctl
products | 2 **
1 tables changed, 0 rows added(+), 2 rows modified(*), 0 rows deleted(-)

+----+----------+---------+-------+
| id | name     | price   | stock |
+----+----------+---------+-------+
| 1  | Keyboard | 159.20  | 50    |
| 2  | Mouse    | 71.60   | 120   |
| 3  | Monitor  | 1299.00 | 20    |
+----+----------+---------+-------+

commit o93jcrjiirvurhsd92dtsi9cv5kfoctl
Author: admin <admin@quzuo.net>
Date:  Sun Oct 18 11:10:38 +0800 2026

        促销：Keyboard 与 Mouse 打八折

commit 53lb9ufgdfk6m60dob20n13imvpsqbpo
Author: admin <admin@quzuo.net>
Date:  Sun Oct 18 11:10:27 +0800 2026

        初始库存表：新增 products 表与 3 条基础数据

合并输出 Fast-forward（快进合并，主干没有分叉提交时默认行为）；统计行 1 tables changed, 0 rows added(+), 2 rows modified(*), 0 rows deleted(-) 给出行级变更计数。至此闭环完成。

四、闭环后的常用查看命令

4.1 提交历史 dolt log

dolt log -n 2

实测回显（见 3.5 节末尾，含哈希、作者、日期、提交说明）。需要更紧凑的单行视图时：

dolt log --oneline -n 2

实测回显：

o93jcrjiirvurhsd92dtsi9cv5kfoctl 促销：Keyboard 与 Mouse 打八折
53lb9ufgdfk6m60dob20n13imvpsqbpo 初始库存表：新增 products 表与 3 条基础数据

4.2 仓库当前状态 dolt status / dolt ls

dolt status
dolt ls

实测回显：

On branch main
nothing to commit, working tree clean

Tables in working set:
        products

4.3 放弃未提交修改 dolt reset --hard

误改了数据且尚未 commit 时，一条命令回到最近提交：

dolt sql -q "update products set stock = 999 where id = 1"
dolt status
dolt reset --hard
dolt sql -q "select stock from products where id = 1"

实测回显：

On branch main
Changes not staged for commit:
  (use "dolt add <table>" to update what will be committed)
  (use "dolt checkout <table>" to discard changes in working directory)
        modified:         products

+-------+
| stock |
+-------+
| 50    |
+-------+

⚠️ 注意：dolt reset --hard 会丢弃所有未提交修改，不可恢复；已提交的历史版本回退与时间旅行查询属于进阶能力，见《Dolt 版本化 SQL 实战》。

五、常见问题

Q1：dolt commit 报错要求配置用户信息怎么办？ 回显形如 Author identity unknown。执行 dolt config --global --add user.name "admin" 与 dolt config --global --add user.email "admin@quzuo.net"（取值换成自己的）后重试。

Q2：dolt version 出现 Warning: unable to query latest released Dolt version 正常吗？ 正常。这是联网查询最新版本失败（离线/网络受限）的提示，不影响本地功能；离线服务器会常态出现，可忽略。

Q3：同一个目录能放多个数据库吗？ 不能。Dolt 的「一个目录 = 一个数据仓库」；如需一个服务端带多个库，在服务端数据目录下为每个库各建一个子目录（各自 dolt init），启动 dolt sql-server 时每个子目录自动成为一个 database，见《Dolt 集成实战》。

Q4：在哪里能看到实际数据文件？ 在仓库目录的 .dolt/noms/ 下，是内容寻址的块存储，不要手工改动；备份直接复制整个仓库目录即可。

六、参考链接

官方 Quick Start：https://docs.dolthub.com/introduction/quickstart
安装环节：见《Dolt 安装部署指南》
进阶版本化操作（冲突解决、时间旅行、存储过程）：见《Dolt 版本化 SQL 实战》
MySQL 协议接入：见《Dolt 集成实战》
产品定位与选型：见《Dolt 介绍与选型指南》