> For the complete documentation index, see [llms.txt](https://summerain-1.gitbook.io/summerain/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://summerain-1.gitbook.io/summerain/user-and-operations/migrations.md).

# Schema Migrations

The backend owns additive MySQL schema migrations through `repository.ApplySchemaMigrations(db)`. Startup must stop immediately when that function returns an error.

The runner:

* reserves one SQL connection and holds a database-scoped MySQL advisory lock;
* creates `schema_migrations` when needed;
* verifies the immutable SHA-256 checksum of every previously applied version;
* applies missing operations in version order;
* probes `information_schema` before adding columns or indexes;
* records a version only after all of its operations succeed.

MySQL DDL commits implicitly. Therefore every operation is additive and safe to retry after interruption. Never edit an applied migration. Append a higher version instead. Destructive renames, column drops, and table drops require a separate compatibility and rollback plan and are intentionally absent from the V2 bootstrap migrations.

Current versions:

* `2026071501`: add V2 pipeline metadata and indexes to `images`.
* `2026071502`: create V2 variants, upload sessions/parts, processing jobs, and transactional outbox tables.
* `2026071601`: add the singleton row used to serialize global upload-capacity reservations across backend instances.
* `2026071602`: add storage-reference lookup and bounded control-plane retention indexes.
* `2026071603`: add remote backend, endpoint, and bucket lineage columns and an index. Historical rows remain unclassified for the separate migration tool; server startup never infers their storage target.


---

# 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://summerain-1.gitbook.io/summerain/user-and-operations/migrations.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.