# storage Guardrails

> Canonical path: `guardrails/storage/README.md`

This README lists executable guardrails for the `storage` domain in
recommended order.

- [`tidb-migration-history-test.sh`](./tidb-migration-history-test.sh) —
  exercises the TiDB migration history guard against isolated Git fixtures.
- [`tidb-migration-history.sh`](./tidb-migration-history.sh) — keeps existing
  TiDB migration history immutable and requires each candidate migration
  version to be unique and above the target ref's current high-water mark.

## TiDB migration target

`tidb-migration-history.sh` compares committed `HEAD` with
`merge-base(target, HEAD)`. Set `AGENTTEAM_TIDB_MIGRATION_BASE_REF` to the exact
target ref used by the integration gate. The value must resolve to a commit.
The script defaults to `origin/main` as a local convenience; shared and final
integration checks must pass the intended current target's full commit SHA
explicitly. In particular, `scripts/ci-backend-required.sh validate` rejects a
missing target and mutable names such as `origin/main`.
`make regression-fast` resolves its fetched `origin/main` to a full SHA before
calling that integration check.

The guard prints the target input, resolved commit, merge-base, and target
maximum migration version. It reads the high-water mark from the target
commit's current `internal/tidb/migrations` tree, so the final integration
check detects a migration version that entered the target after a candidate
branch was created.

The candidate is committed `HEAD`. Untracked, staged, or unstaged changes
under `internal/tidb/migrations` fail closed because they are outside that
candidate snapshot. Existing migration changes, deletions, type changes, and
renames are rejected. Renames are deliberately evaluated as a deletion plus
an addition. There is no environment skip. A production migration repair is
accepted only when `tidb-migration-repairs.tsv` pins the path and exact
before/after Git blob ids. Besides a failed migration that goose did not
record, this exception may remove a newly discovered destructive data mutation
for databases that have not applied it yet. Such a repair must not replay the
migration or infer, restore, or otherwise rewrite data in databases where
goose already recorded it.