[jeff377]

Part of #512. This is the second step. It uses the records added in #517 to skip comparing tables that have not changed.

What changes

• UpgradeOptions.CompareMode is Fast by default.
  • A table is taken as unchanged without reading the database catalog when its record in st_table_upgrade meets three conditions:
    • the status is a success (Succeeded or Verified);
    • the record was written under this SchemaFormat;
    • the record's hash equals the hash of the definition's current schema.
  • Any other table is compared in full.
  • Full always compares. It is the only way to find a change made to a table by hand.
  • db upgrade --full-compare selects Full.
• The store reads its records once per instance. It reads only table_name, status, format_version and schema_hash, row by row with a reader. schema_xml is never read for this, so a database with thousands of tables stays small in memory.
• A compare that finds nothing to change records the table. The next fast compare can then rely on it, and a record left Upgrading or Failed gets corrected.
  • The new record is Verified unless this format wrote the existing record.
  • The format check ignores Verified records. Without this, a deployment that changed no table would block rolling back to an older tool.
  • Dry runs write nothing.
  • If the records cannot be read, the table is compared in full instead.
• Where it applies:
  • TableSchemaBuilder.Execute and DatabaseInitializer use the fast path.
  • GetCommandText and CompareToDiff always compare in full.
  • SharedDatabaseState uses Full, because a persistent local test database may be changed by hand.
• SchemaFormat remarks now say the version must also be raised when what a comparison detects changes, since fast compare trusts records written under the current version.
• Documentation: db upgrade usage text, the DbManager help, and the CLI table in database-settings-guide (en and zh-TW).

Measured

These numbers were measured while designing this change, against local containers. The setup was 26 framework tables in 3 databases, averaged over 5 rounds. The last column reads all records of a database in one query, which is the approach this PR implements.

Database	Full compare	One record query per table	One query per database
Oracle	599 ms	84 ms	1.5 ms
SQL Server	288 ms	43 ms	1.5 ms
PostgreSQL	56 ms	12 ms	0.9 ms
MySQL	48 ms	14 ms	1.1 ms
SQLite	1.2 ms	0.5 ms	0.2 ms

Compatibility

The public API changes are additions only:

• UpgradeCompareMode
• UpgradeOptions.CompareMode
• TableUpgradeStatus.Verified, added last so existing values keep their numbers
• TableUpgradeRecordStore.IsRecordedAsCurrent and TryRecordUnchanged

Behaviour change: with the default options, TableSchemaBuilder.Execute and db upgrade no longer notice a table changed by hand while its record is current. Use Full for that.

Verification

• dotnet build Polhem.slnx -c Release: 0 warnings.
• ./test.sh locally with all five databases. Everything passes except Generate_iOS_Builds, which fails because the local Xcode does not match the iOS workload; it is unrelated to this change.
• New tests:
  • record summaries and TryRecordUnchanged on all five databases;
  • TableSchemaBuilder recording a current table;
  • DatabaseInitializer:
    • fast versus full when a table was dropped by hand;
    • falling back to a full compare for Failed, Upgrading, an old format, and a stale hash;
    • dry runs writing nothing;
    • a deployment with no changes leaving no record that blocks an older tool;
  • --full-compare on the command line.
• Adversarial review of the diff before opening, with fixes:
  • Rollback (P2): verification wrote this format, so a no-op deployment blocked rolling back to an older tool. This led to the Verified status.
  • Unreadable records: these now fall back to a full compare instead of throwing.
  • Docs: the SchemaFormat remarks were incomplete; they are updated as described above.
  • Left as is:
    • A verification can overwrite a Failed record that another process wrote at the same moment. Only the diagnostic text is lost, and the next run compares in full again.
    • DatabaseInitializer keeps its own record cache. It is not updated when a table is upgraded, which costs at most one extra compare.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud