[jeff377]

Part of #512. This is the first step: per-table upgrade records, and the guard that stops an older tool from undoing a newer tool's upgrade.

What changes

• st_table_upgrade, one per database, one row per upgraded table:

  • the SchemaFormat and framework version of the tool that ran the upgrade;
  • the status (Upgrading / Succeeded / Failed) and the error;
  • the applied TableSchema as XML, and its SHA-256.

  The table is created on first use, from a schema built in code, through each dialect's create builder. It is not declared in any definition.

• TableUpgradeOrchestrator.Execute does three things, in order:

  1. Refuses the upgrade, with nothing changed, when the database's highest recorded format is above SchemaFormat.Current.
  2. Marks the table Upgrading before any statement runs, so an older tool is refused even after a failed or half-finished upgrade.
  3. Records the outcome. A failure keeps the schema of the last successful upgrade.

• What creates no record:

  • an empty plan;
  • TableSchemaBuilder.GetCommandText;
  • a dry run.

• DatabaseInitializer.UpgradeTables checks each database once. A database a newer format upgraded becomes a single problem in the report, and none of its tables is touched (dry run included).

• SchemaFormat.Current starts at 1.

Compatibility

Public API changes are additions only:

• SchemaFormat
• TableUpgradeRecordStore
• TableUpgradeRecord
• TableUpgradeStatus
• UpgradePlan.DefineTable, as an init property

Existing callers stay binary compatible. A plan built by hand without DefineTable runs without a record, but the format guard still applies.

Known limits (left to later phases of #512)

• A table that is already up to date gets no record until something changes it. The fast compare in phase 2 needs a record for such tables, so it will write one after a full compare finds no difference.
• Two processes upgrading the same table at the same moment can leave a misleading record: the losing process's Failed can overwrite the winner's Succeeded. The data is unaffected.
• The format check and the record write are not atomic, so an old and a new tool racing can both pass the check once. Later runs are still blocked by the other rows.

Verification

• dotnet build Polhem.slnx -c Release: 0 warnings.
• ./test.sh locally with all five databases, everything passing except Generate_iOS_Builds, which fails because the local Xcode does not match the iOS workload. That test is unrelated to this change.
• New tests:
  • TableUpgradeRecordDbTests covers success, failure and the newer-format refusal on each database, plus an empty plan and a plan without its definition.
  • Two DatabaseInitializerSqliteTests cover records after a build, and one report per newer-format database.
• An adversarial review of the diff before opening this PR led to these fixes:
  • a record write that fails after the table changed no longer reports the upgrade as failed;
  • the update and the insert use separate parameters;
  • the table_name column is widened to 128;
  • framework versions are compared as versions, not as text.

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
87.5% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud