Study/docs/MIGRATION.md
Elijah 7125dec3e0
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 30s
Restore a full backup from Settings
Settings → Data → Import gets "Restore a full backup" in place of the V1
import row. The zip from "Download backup" is uploaded and replaces the
database, every setting and the uploaded files on the running server:

- the staged database is upgraded to this schema (newer backups are refused),
  saved keys are re-encrypted for this server's key, interrupted jobs are
  marked, and the restoring session is carried over;
- a pre-restore snapshot is written, running generations stop, and the file
  is swapped under the open DB handle (DB.replaceWith); uploads and media are
  copied into place and background work restarts.

The /api/import/v1 endpoint stays for the V1 cutover (docs/MIGRATION.md).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 12:33:42 -07:00

1.7 KiB

Importing V1 safely

V1 code remains on main at 7bd0a9a and in history. V2 has a separate schema and must use a separate data folder. It never upgrades a production V1 database in place.

  1. Use V1's backup facility to make a consistent SQLite copy. If copying files yourself, stop V1 first; copying only a live WAL-mode .db can omit recent writes.
  2. Keep the original and a verified backup untouched. Start V2 with an empty V2 volume.
  3. Settings no longer shows the V1 import (its place went to restoring a full V2 backup), but the endpoint remains. While signed in, preview the backup copy with POST /api/import/v1?preview=1 (multipart field file, header X-Requested-With: studydesk), then import it without ?preview=1.
  4. Review the reported counts/skipped items, then explicitly import. V2 opens the submitted SQLite file read-only and creates new IDs in one transaction. A failed import rolls back.
  5. Compare class/folder/deck/quiz counts and representative questions, rationales, attempts and scheduling. V1's passwords, provider settings and share URLs are not reused. Recreate links deliberately. Running the import again creates another set of content.

The importer supports V1 classes, material groups, decks/cards, quiz sets/questions/options, completed attempts, spaced-repetition card state and activity where present. It reports unsupported/skipped records. Older optional game features are not migrated as games. V1 JSON quiz/flashcard exports can also be pasted/uploaded in a class's Import dialog.

Portable V2 JSON exports are useful for migration between apps; full ZIP backups are needed to preserve progress, documents, settings and credentials. See DEPLOYMENT.md for recovery.