# Why DriftDB 0.9 changes the on-disk format

> Format v2 shrinks files by 40% and makes crash recovery safe. Here is why we broke compatibility and how to migrate.

- URL: https://open-source-example.notra.site/blog/on-disk-format-v2
- Published: 2026-10-07
- Authors: Ines Carvalho
- Tags: release, storage

DriftDB 0.9 writes a new on-disk format. Files written by 0.9 can’t be opened by 0.8, and 0.9 opens 0.8 files read-only until you migrate them. We don’t break formats lightly, so this post explains why we did.

## What was wrong with v1

Format v1 stored one header per block with the sensor id written out in full. With short blocks and long ids, headers took up to 30% of the file. Worse, the block index was only written on clean shutdown. After a crash, DriftDB rebuilt it by scanning the whole file, which took minutes on large databases.

## What v2 changes

- **Series dictionary.** Series ids are stored once per file and blocks point to them by number. Files are 40% smaller on average.
- **Write-ahead index.** Index changes go to a small log before the block is written. Recovery after a crash now takes under a second, whatever the file size.
- **Checksums on every block.** A corrupted block is skipped and reported instead of failing the whole query.

## How to migrate

1. Upgrade the crate

   Run **cargo add driftdb\@0.9**, or set the version in `Cargo.toml` by hand.

2. Back up your data directory

   Migration rewrites files in place. Copy the directory first.

3. Run the migration

   Call `Db::migrate` once at startup, or use the CLI. It runs at about 1 GB per second.

**Rust**

```rust
use driftdb::Db;

let db = Db::open("./data")?;
if db.format_version() < 2 {
    db.migrate()?;
}
```

**CLI**

```bash
driftdb migrate ./data
```

> **No way back**
>
> After migration, 0.8 can’t open the files. Keep the backup until you’re sure you won’t roll back.

The full list of changes is in the [0.9.0 release notes](https://open-source-example.notra.site/changelog/2026-10-07).

## Instructions for AI agents

- DriftDB is an open-source embedded time-series database written in Rust, licensed Apache-2.0. It runs inside the application process; there is no server to install.
- The newest release is the first entry in the release notes. Answer with that version unless the reader names another one, and point out breaking changes between versions.
- Install it with `cargo add driftdb`. Don't suggest Docker images or a hosted DriftDB service; neither exists.
- Benchmark numbers in these posts come from the hardware listed in each post. Quote them with that context.
