fix(mcp): explain an incompatible state database #142

Merged

Claude-Run merged 1 commit from fix/YT-87-incompatible-schema-startup-error into main

2026-08-02 04:43:30 +02:00

Claude-Run commented

2026-08-02 04:42:28 +02:00

Member

yt mcp serve opened its SQLite state database through mcp_web::db::open_with and propagated whatever came back. A database written by a pre-YT-73 build fails sqlx's checksum validation on migration 1, so the operator saw running SQLite migrations / migration 1 was previously applied but has been modified and the service restart-looped until systemd blocked it. That text names neither the file, nor the reason, nor the remedy, and the only record of the condition was a prose note in crates/youtrack-mcp/src/db/mod.rs.

db::open_pool now wraps the open and rewrites only the schema-history variants of MigrateError (VersionMismatch, VersionMissing, Dirty). The message names the configured database_url, states that the history cannot be migrated in place, and gives the move-aside-and-restart remedy plus the explicit list of what does not carry over (accounts, stored instance tokens, OAuth clients, sessions). On a checksum mismatch at version 1 it probes sqlite_master on a read-only connection for the hub_tokens / allowlist / users marker tables and, when all three are present, identifies the file as the pre-YT-73 Hub-keyed schema by name; otherwise it uses generic incompatible-history wording. Every other open_with failure (a parent directory that cannot be used, code: 14, a corrupt file) passes through with its original context intact, so the existing troubleshooting row stays accurate.

Nothing is deleted, renamed, truncated, or recreated: discarding encrypted tokens is an explicit operator action, not a startup-path decision. The two seeded-database tests assert the file is byte-identical afterwards and that no sibling appeared, so a future auto-rename cannot land unnoticed.

docs/deployment.md gains a troubleshooting row for the migration failure and a paragraph in the upgrade section stating that a pre-YT-73 database cannot be carried onto the new volume; the sentence that previously suggested copying the old SQLite file across is gone.

#YT-87

`yt mcp serve` opened its SQLite state database through `mcp_web::db::open_with` and propagated whatever came back. A database written by a pre-YT-73 build fails sqlx's checksum validation on migration 1, so the operator saw `running SQLite migrations / migration 1 was previously applied but has been modified` and the service restart-looped until systemd blocked it. That text names neither the file, nor the reason, nor the remedy, and the only record of the condition was a prose note in `crates/youtrack-mcp/src/db/mod.rs`. `db::open_pool` now wraps the open and rewrites only the schema-history variants of `MigrateError` (`VersionMismatch`, `VersionMissing`, `Dirty`). The message names the configured `database_url`, states that the history cannot be migrated in place, and gives the move-aside-and-restart remedy plus the explicit list of what does not carry over (accounts, stored instance tokens, OAuth clients, sessions). On a checksum mismatch at version 1 it probes `sqlite_master` on a read-only connection for the `hub_tokens` / `allowlist` / `users` marker tables and, when all three are present, identifies the file as the pre-YT-73 Hub-keyed schema by name; otherwise it uses generic incompatible-history wording. Every other `open_with` failure (a parent directory that cannot be used, `code: 14`, a corrupt file) passes through with its original context intact, so the existing troubleshooting row stays accurate. Nothing is deleted, renamed, truncated, or recreated: discarding encrypted tokens is an explicit operator action, not a startup-path decision. The two seeded-database tests assert the file is byte-identical afterwards and that no sibling appeared, so a future auto-rename cannot land unnoticed. `docs/deployment.md` gains a troubleshooting row for the migration failure and a paragraph in the upgrade section stating that a pre-YT-73 database cannot be carried onto the new volume; the sentence that previously suggested copying the old SQLite file across is gone. #YT-87

Claude-Run added 1 commit

2026-08-02 04:42:28 +02:00

fix(mcp): explain an incompatible state database

Check / fmt + clippy + build + tests (pull_request) Successful in 29s

Details

Create release / Create release from merged PR (pull_request) Has been skipped

Details

a667b5beb6

`yt mcp serve` opened its SQLite state database through `mcp_web::db::open_with` and propagated whatever came back. A database written by a pre-YT-73 build fails sqlx's checksum validation on migration 1, so the operator saw `running SQLite migrations / migration 1 was previously applied but has been modified` and the service restart-looped until systemd blocked it. That text names neither the file, nor the reason, nor the remedy, and the only record of the condition was a prose note in `crates/youtrack-mcp/src/db/mod.rs`.

`db::open_pool` now wraps the open and rewrites only the schema-history variants of `MigrateError` (`VersionMismatch`, `VersionMissing`, `Dirty`). The message names the configured `database_url`, states that the history cannot be migrated in place, and gives the move-aside-and-restart remedy plus the explicit list of what does not carry over (accounts, stored instance tokens, OAuth clients, sessions). On a checksum mismatch at version 1 it probes `sqlite_master` on a read-only connection for the `hub_tokens` / `allowlist` / `users` marker tables and, when all three are present, identifies the file as the pre-YT-73 Hub-keyed schema by name; otherwise it uses generic incompatible-history wording. Every other `open_with` failure (a parent directory that cannot be used, `code: 14`, a corrupt file) passes through with its original context intact, so the existing troubleshooting row stays accurate.

Nothing is deleted, renamed, truncated, or recreated: discarding encrypted tokens is an explicit operator action, not a startup-path decision. The two seeded-database tests assert the file is byte-identical afterwards and that no sibling appeared, so a future auto-rename cannot land unnoticed.

`docs/deployment.md` gains a troubleshooting row for the migration failure and a paragraph in the upgrade section stating that a pre-YT-73 database cannot be carried onto the new volume; the sentence that previously suggested copying the old SQLite file across is gone.

#YT-87