sessions_cmd_journal_mode.py 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110
  1. """`hermes sessions set-journal-mode delete|wal` — the offline self-service path for #100896.
  2. ``database.journal_mode: delete`` can never self-apply on a store that is already WAL:
  3. ``apply_wal_with_fallback`` deliberately never live-downgrades (#68545 — other gateway/cron/worker connections
  4. may hold uncheckpointed WAL commits). Before this command the only escape hatch was an undocumented hand-run
  5. ``PRAGMA journal_mode=DELETE``. This runs it under the same admission the maintenance paths use: refuse while
  6. ANY foreign process holds the file or a sidecar (``foreign_state_db_holders``), flip without waiting out openers
  7. (``_set_journal_mode_no_wait``), then verify the header bytes 18/19 SQLite writes for the mode.
  8. """
  9. from __future__ import annotations
  10. import sqlite3
  11. from pathlib import Path
  12. from typing import Optional
  13. # SQLite file header: bytes 18 (write version) / 19 (read version) are 1 for rollback-journal, 2 for WAL.
  14. _HEADER_VERSION_BYTES = {"delete": (1, 1), "wal": (2, 2)}
  15. _MODE_BY_HEADER_VERSION = {v: k for k, v in _HEADER_VERSION_BYTES.items()}
  16. def _header_mode(db_path: Path) -> str:
  17. """Journal mode as the on-disk header reports it (no SQLite connection is open in this process here)."""
  18. with open(db_path, "rb") as fh:
  19. head = fh.read(20)
  20. if len(head) < 20 or head[:16] != b"SQLite format 3\x00":
  21. return "not-a-database"
  22. return _MODE_BY_HEADER_VERSION.get((head[18], head[19]), f"unknown({head[18]}/{head[19]})")
  23. def _refusal(target: str, current: str, *, on_cross_vm_fs: bool) -> Optional[str]:
  24. """Admission checks independent of holder discovery, which is enforced for every platform."""
  25. if current == "not-a-database" or current.startswith("unknown("):
  26. return (f"its file header reads {current}, so it is not a Hermes SQLite store this command can convert "
  27. "(pass --db PATH to point at one).")
  28. if target == "wal" and on_cross_vm_fs:
  29. return ("WAL shared memory silently corrupts on cross-VM filesystems (virtiofs/9p — Docker Desktop, "
  30. "OrbStack, Lima bind mounts). Keep this store on journal_mode=delete or move it to a native "
  31. "filesystem.")
  32. return None
  33. def cmd_set_journal_mode(args) -> int:
  34. from hermes_state import _default_db_path
  35. from hermes_state_holders import describe_holder_pid, foreign_state_db_holders
  36. from hermes_state_wal import (_path_on_cross_vm_fs, _set_journal_mode_no_wait, is_sqlite_wal_reset_vulnerable,
  37. resolve_journal_mode)
  38. target = args.mode
  39. db_path = Path(getattr(args, "db", None) or _default_db_path())
  40. if not db_path.exists():
  41. print(f"No database at {db_path} (nothing to convert).")
  42. return 1
  43. try:
  44. current = _header_mode(db_path)
  45. except OSError as exc:
  46. print(f"✗ Cannot read {db_path}: {exc}")
  47. return 1
  48. if current == target:
  49. print(f"✓ {db_path} is already journal_mode={target}.")
  50. return 0
  51. refusal = _refusal(
  52. target, current, on_cross_vm_fs=target == "wal" and _path_on_cross_vm_fs(str(db_path))
  53. )
  54. if refusal:
  55. print(f"✗ Refusing to change the journal mode of {db_path}: {refusal}")
  56. return 1
  57. if target == "wal" and is_sqlite_wal_reset_vulnerable():
  58. print(f"✗ Refusing to enable WAL: the linked SQLite {sqlite3.sqlite_version} has the WAL-reset bug "
  59. "(https://sqlite.org/wal.html#walresetbug). Upgrade to 3.51.3+ first.")
  60. return 1
  61. holders = foreign_state_db_holders(db_path)
  62. if getattr(args, "force", False):
  63. # Same override the optimize/prune dispatcher honours, narrowed: --force waives only an incomplete
  64. # scan (the pid <= 0 sentinel), never a process the scan actually found.
  65. holders = [holder for holder in holders if holder[0] > 0]
  66. if holders:
  67. print(f"✗ Refusing to change the journal mode of {db_path}: other processes hold it open "
  68. "(a live switch would destroy their uncheckpointed commits). Stop them and re-run:")
  69. for pid, target_path in holders:
  70. print(f" pid {pid} — {describe_holder_pid(pid) if pid > 0 else 'scan'}: {target_path}")
  71. return 1
  72. # timeout=0: any opener that appeared between the scan and the flip makes the pragma fail with
  73. # 'database is locked' instead of sneaking the switch between a writer's transactions.
  74. try:
  75. conn = sqlite3.connect(str(db_path), timeout=0.0, isolation_level=None)
  76. except (OSError, sqlite3.Error) as exc:
  77. print(f"✗ Cannot open {db_path}: {exc}")
  78. return 1
  79. try:
  80. try:
  81. reported = _set_journal_mode_no_wait(conn, target.upper())
  82. except sqlite3.OperationalError as exc:
  83. print(f"✗ journal_mode={target.upper()} refused: {exc} (another opener appeared; nothing was changed)")
  84. return 1
  85. finally:
  86. conn.close()
  87. try:
  88. after = _header_mode(db_path)
  89. except OSError as exc:
  90. print(f"✗ Cannot re-read {db_path} after the switch: {exc}")
  91. return 1
  92. if after != target:
  93. print(f"✗ SQLite reported journal_mode={reported or '?'} but the file header reads {after}; not converted.")
  94. return 1
  95. print(f"✓ {db_path}: journal_mode {current} → {after} (header verified).")
  96. configured = resolve_journal_mode()
  97. if configured != target:
  98. print(f" Note: config.yaml has database.journal_mode: {configured} — the next open would switch the file "
  99. f"back. Set `database.journal_mode: {target}` in config.yaml to keep it.")
  100. return 0