---
title: "Write-ahead log (WAL)"
description: "A write-ahead log (WAL) is a durability mechanism where every change is recorded in an append-only log before it's applied to the main data files, enabling crash recovery."
canonical: "https://motherduck.com/glossary/write-ahead-log/"
related:
  - title: "DuckLake | MotherDuck Docs"
    url: "https://motherduck.com/docs/concepts/ducklake/"
  - title: "Practical Postgres CDC with Streamkap + MotherDuck | MotherDuck"
    url: "https://motherduck.com/videos/postgres-cdc-streamkap-motherduck/"
  - title: "DuckLake Architecture Deep Dive"
    url: "https://motherduck.com/blog/ducklake-architecture-deep-dive/"
gated_asset:
  title: "DuckLake on MotherDuck"
  url: "https://motherduck.com/product/ducklake/"
---

# Write-ahead log (WAL)

> A write-ahead log (WAL) is a durability mechanism where every change is recorded in an append-only log before it's applied to the main data files, enabling crash recovery.

## Overview

The write-ahead logging protocol is one of the most common techniques for giving a database durability without sacrificing performance. The core rule is simple: a change is written to a sequential log file and flushed to disk *before* it is applied to the actual data pages, and before the transaction that made it is considered committed. If the process crashes afterward, the database can replay the log on startup to redo any committed changes that hadn't yet made it into the main data files.

## How WAL Works

Because appending to a log is a fast, sequential I/O operation, WAL lets a database acknowledge a commit quickly without needing to immediately rewrite scattered data pages on disk. Over time the log grows, so databases periodically run a **checkpoint**: applying all logged changes to the main data files and then truncating the log, so recovery after a crash only needs to replay the (small) log since the last checkpoint.

## DuckDB's WAL

DuckDB writes a `<database>.wal` file alongside its main `.duckdb` database file. Every change made outside of a checkpoint is appended to this WAL first. If DuckDB is closed uncleanly, the next time the database is opened it replays the WAL to recover any changes that weren't yet checkpointed. Running `CHECKPOINT` explicitly merges the WAL into the main database file and clears it:

```sql
CHECKPOINT;
```

DuckDB also checkpoints automatically when the WAL grows past a configurable threshold or when the database is closed cleanly.