> For the complete documentation index, see [llms.txt](https://litedb.gitbook.io/litedb-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://litedb.gitbook.io/litedb-docs/architecture_and_design/transaction_and_recovery/wal.md).

# WAL 格式与文件写入

WAL 位于独立目录，正式段名为 20 位零填充代号：

```
00000000000000000001.wal
00000000000000000002.wal
```

打开时选择代号最大的正式段作为活动 WAL，并清理遗留 `.wal.tmp` 文件。

## 文件头

WAL 格式版本为 2，文件头固定 32 字节：

| 偏移 | 大小 | 字段                        |
| -: | -: | ------------------------- |
|  0 |  4 | 魔数 `LDWL`                 |
|  4 |  2 | 版本                        |
|  6 |  2 | 头大小                       |
|  8 |  8 | WAL generation            |
| 16 |  8 | checkpoint transaction ID |
| 24 |  4 | CRC32                     |
| 28 |  4 | 保留                        |

generation 必须大于 0，并与文件名一致。

## 记录头

每条 WAL 记录有 48 字节头：

| 偏移 | 大小 | 字段         |
| -: | -: | ---------- |
|  0 |  4 | 魔数 `LWR1`  |
|  4 |  2 | 版本         |
|  6 |  1 | 记录类型       |
|  7 |  1 | 保留         |
|  8 |  8 | 记录总长度      |
| 16 |  8 | LSN        |
| 24 |  8 | 事务 ID      |
| 32 |  8 | payload 长度 |
| 40 |  4 | 整条记录 CRC32 |
| 44 |  4 | 保留         |

LSN 是记录在当前 WAL 文件中的物理起始偏移。扫描要求记录的 LSN 与当前偏移一致。

## 记录类型

WAL 只有三种记录：

* `Begin`：开始事务，无 payload；
* `FileWrite`：一个物理文件 after-image；
* `Commit`：提交事务，无 payload。

没有 Abort 记录和 undo 数据。未提交事务的日志保留到 checkpoint，但恢复时直接忽略。

## FileWrite

文件目标由 `FileKind + object_id` 表示，而不是直接保存任意路径。`resolve_target` 将其限定映射到数据库已知布局，避免 WAL 记录把写入导向数据目录之外。

支持四种写入模式：

| 模式          | 语义                      |
| ----------- | ----------------------- |
| `Overwrite` | 从 offset 覆盖 after-image |
| `Replace`   | 用完整 after-image 替换文件    |
| `Delete`    | 删除目标文件                  |
| `Truncate`  | 把文件调整到 offset 指定的长度     |

目标种类覆盖集合、标量索引、向量索引和 MetaStore。

## 扫描与资源限制

WAL 扫描验证魔数、版本、长度、LSN、事务 ID 和 CRC。默认限制包括：

* 单记录最大 512 MiB；
* 扫描总量最大 4 GiB；
* 最多 2,000,000 条记录。

这些限制用于阻止损坏长度字段触发无界内存分配，也会在提交前由预算验证复用。

文件末尾若只有不完整的记录头或记录体，可以截断到最后一个完整记录边界。一个完整但校验失败的记录属于损坏，不能当作普通撕裂尾部忽略。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://litedb.gitbook.io/litedb-docs/architecture_and_design/transaction_and_recovery/wal.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.