Upgrade von Legacy-SQLite-Shards

Beim Start werden unterbrochene Re-Embed-Swaps wiederhergestellt, libSQL-DiskANN-Indizes auf die aktuelle Turso-Engine konvertiert und anschließend das Legacy-Shard-Schema verifiziert oder aktualisiert. Die Engine-Konvertierung läuft auch, wenn ein Store bereits einen abgeschlossenen Legacy-Migrationsmarker hat, und erhält gespeicherte Vektoren ohne erneutes Embedding. Jede konvertierte Datenbank wird als <database>.pre-tursodb-<timestamp>.bak gesichert.

Unter macOS und Linux können mehrere OpenCode-Sitzungen denselben storagePath über Turso’s experimentelles multiprocess_wal teilen (jeder Prozess muss denselben Modus nutzen — nach dem Upgrade alle Sitzungen neu starten). Unter Windows lehnt die Engine dieses Flag ab, sodass nur eine OpenCode-Sitzung die Speicherdatenbanken gleichzeitig besitzen kann.

tursoMultiprocessWal: false öffnet stattdessen im Single-Owner-Modus: andere Prozesse scheitern dann mit database is locked, statt den Store zu teilen. Das ist die sicherere Wahl, wenn Nicht-Plugin-Tools dieselben Dateien anfassen, weil ein schreibender fremder SQLite-Prozess den WAL-Index von Turso veraltet macht und der eigene nächste Write still verloren geht. tursoAutoHeal (Standard true) verschiebt die Index-Sidecars -shm/-tshm eines Stores nach storagePath/recovery/<db>-<timestamp>/ und versucht einmal erneut, wenn ein Open wegen veraltetem WAL-Index scheitert — nachdem eine Kopie der Hauptdatenbank verifiziert wurde. Eine nicht leere -wal wird nie verschoben, sodass committed aber noch nicht checkpointete Transaktionen erhalten bleiben; nur fehlende oder 0-Byte--wal werden entfernt. Gleichzeitige Sitzungen serialisieren das Heilen über storagePath/recovery/<db>.lock.

Beim ersten Start nach dem Upgrade migriert opencode-mem vorhandene Memory-Shard-Datenbanken automatisch in das native Turso/libSQL-Vektorformat:

Jeder Shard wird vor dem Rewrite als <shard>.db.legacy.bak gesichert
Der Fortschritt wird pro Shard in <shard>.db.turso-migrate.json verfolgt
Ein globaler Marker .turso-migrated wird erst geschrieben, wenn alle Shards erfolgreich verifiziert wurden
Normale Inserts und Deletes entwerten eine abgeschlossene Shard-Migration nicht; beim Start wird weiterhin geprüft, dass Vektoren lesbar sind und zu den gespeicherten Dimensionen passen
Während der Migration keine mehreren OpenCode-Instanzen gegen denselben storagePath betreiben; eine Lock-Datei (.turso-migrate.lock) verhindert parallele Migration
Manuelle Dimensionsmigrationen nutzen .turso-operation.lock; andere Plugin-Prozesse lehnen neue Memory-Writes ab, bis die Migration fertig ist
Locks verfallen nach 30 Minuten ohne Fortschritts-Timestamp-Update (oder Datei-Änderungszeit, falls der Timestamp fehlt), auch wenn der besitzende Prozess noch lebt. Dieses Lease nutzt Wanduhrzeit: ein Vorwärtssprung der Uhr um mehr als 30 Minuten kann eine laufende Operation früh beenden; ein Rückwärtssprung oder ein zukunftsdatiertes Lock kann ein inertes Lock verlängern. Locks tragen eine eindeutige Acquisition-ID, und Stale-Cleanup entfernt nur die genau inspizierte Datei. Migrationen senden Heartbeats und brechen ab, wenn sie den Besitzverlust feststellen. Stale-Lock-Cleanup wird zur Diagnose geloggt.

Wird die Migration unterbrochen, setzt der nächste Start die Arbeit aus dem Backup automatisch fort.

Wird ein Shard inkompatibel (z. B. nach Änderung von embeddingDimensions), werden Writes blockiert und die Originaldatenbank bleibt unberührt. Nutze die Re-Embed-Migration der Web-UI, um einen Ersatz zu bauen und zu verifizieren, bevor er an Ort und Stelle getauscht wird. Der vorherige Shard bleibt als <shard>.db.pre-reembed-<pid>-<timestamp>.bak verfügbar.