# ath migrate

> Preview and apply a SQL schema migration after a verified backup.

Website: https://ath.fit/docs/migrate/
Markdown: https://ath.fit/docs/migrate.md

ATH v1.1.0 · MIT license. Documentation source: [070754a](https://github.com/mwhitham/ath/blob/070754ac465e33d41525c8722c102b56284596f1/src/program.ts). If your installed version differs, check its command help.

v1.1.0 is the latest release on npm. These docs were reviewed against it on 8 November 2026.

## Usage

```text
ath migrate
```

## What it does

Previews upgrading the database SQL schema when it is behind the installed CLI. Migration never runs silently. A verified SQLite backup is created before the first schema write.

Non-interactive commands refuse an outdated database and point here. Until it is migrated, ath check reports "database metadata schema version is 1, expected 2" for a database created by v1.0.0. Requires the sqlite3 command-line tool on PATH for verified backups (same as ath repair when repair candidates exist).

The backup is saved beside the database, with .migration-backup in its name. ATH v1.0.0 cannot open a database migrated to SQL schema 2, but it can still open that backup, without later changes.

## Examples

Review the preview, then apply with --yes and repeat the database ID exactly for non-interactive use.

```text
ath migrate --json
ath migrate -y --confirm-migration <database-id>
```

## Options

| Argument or option | Description |
| --- | --- |
| `[file]` | optional database path; defaults to the one in this folder |
| `--file <path>` | migrate a database other than the one in this folder |
| `--confirm-migration <database-id>` | repeat the database ID exactly for non-interactive use |
| `-y, --yes` | apply the preview after reviewing it |
| `--dry-run` | show the preview and write nothing |
| `--json` | structured preview; never confirms the migration |

## Related commands

- [ath check](https://ath.fit/docs/check/)
- [ath repair](https://ath.fit/docs/repair/)
