Skip to content

schema-baseline.md

Latest commit

 

History

History
86 lines (66 loc) · 4.66 KB

schema-baseline.md

File metadata and controls

86 lines (66 loc) · 4.66 KB
Raw

SQLite clean-install baseline / SQLite 全新安装基线

Traverse Board keeps two database initialization paths:

  • a generated consolidated schema baseline for a database that is proven empty; and
  • the complete, append-only migration history for every existing or uncertain database.

The baseline is an installation optimization. It does not change business authority, create a new schema identity, squash migration history, or make an existing profile eligible for conversion.

Admission boundary / 准入边界

The baseline runs only while holding SQLite's immediate write transaction and only when main.sqlite_schema contains no non-SQLite object. In particular, there must be no schema_migrations table and no user table, index, trigger, or view. An empty schema_migrations table is still an existing history and is not baseline-eligible.

If the proof is absent, the generated artifact is stale, or any object is present, the Store uses the historical migration path. Unknown names/checksums and migration gaps continue to fail closed under the existing validation. No filename, file size, user_version, or guessed application state is used as proof of emptiness.

Atomic construction and provenance / 原子构建与来源

internal/store/clean_install_baseline.sql is generated by replaying the complete v1-to-latest plan into a temporary database and reading its final sqlite_schema. The generator rejects unexpected application seed rows. Generated metadata pins:

  • LatestSchemaVersion;
  • the SHA-256 of the generated SQL;
  • the SHA-256 of the final ordered SQLite schema; and
  • a digest of every historical migration version, name, and canonical checksum.

Run go generate ./internal/store after an intentional migration change. Runtime uses the artifact only if all four proofs still match. It creates all schema objects, inserts the canonical historical migration ledger, validates the ledger and final schema fingerprint, and runs PRAGMA foreign_key_check in one transaction. Only the transaction commit identifies completion. A statement error, cancellation, disk-full condition, or process exit therefore leaves either the complete latest database or no baseline schema; it cannot leave a partial baseline marked as current.

The current v136 artifact contains 360 tables, 245 explicit indexes, 912 triggers, and 2 views. Clean install has no application seed rows; the 136 canonical migration ledger rows are the only generated data.

Backup and restore / 备份与恢复

Before launching a newer binary against a non-empty profile, stop all Traverse Board Desktop, CLI, and API processes and make an offline copy of cyberagent.db. Keep any remaining SQLite journal/WAL sidecar files with the diagnostic copy. A filesystem copy while a writer is active is not a supported backup.

Restoring means stopping every process and restoring one internally consistent backup set. Never delete a non-empty database, replace it with an empty file, remove migration rows, or edit checksums to force the baseline path. Those actions destroy the history that selects safe readers and migrations.

Binary rollback boundary / 旧二进制回滚边界

A baseline-created v136 database has the same schema objects and canonical migration ledger as a v1-to-v136 historical creation. A pre-baseline binary that already knows the identical v1-to-v136 plan can therefore open it. A binary whose LatestSchemaVersion is below the database version cannot open it and is not made safe by this baseline. Use the offline pre-upgrade backup for that downgrade; do not delete newer ledger rows.

Future schema versions keep the same rule. Until the generated artifact is refreshed and equivalence tests pass, a version mismatch disables the optimization and clean install safely returns to historical replay.

Failure recovery / 失败恢复

  1. Stop every process using the profile and preserve the database plus any sidecars.
  2. Fix the underlying storage condition (free space, permissions, device health), then restart. A rolled-back empty database is eligible for a fresh atomic attempt.
  3. If a deterministic baseline defect affects a genuinely empty new profile, use the last known-good binary that already supports schema v136. That binary retains the historical creation path and produces the same latest schema.
  4. If the database contains any user object or durable data, do not try to make it appear empty. Diagnose the historical migration error or restore the offline backup.
  5. Preserve the failing copy for diagnosis. Unknown migration history intentionally remains a hard error rather than an automatic reset.

Architecture and evidence are recorded in ADR 0139.