Migrate Local AI History Safely

Direct answer

A local-AI history migration changes the database representation of user records; it is not a model-file update or a reinstall flow. Start by naming the database, schema version, tables and fields that change, and the meaning of each stored value. Export or preserve a known-good backup fixture, write a migration that transforms the old schema into the new one, and test both row counts and semantic fields. Keep raw user-authored content distinct from derived output, model identity, parser version, and UI state. If a field cannot be migrated without guessing, retain the original value or expose a read-only recovery state rather than silently dropping it. The repository contains several separate Room databases rather than one global AI-history database. TranslationDatabase declares version 2 and a v1-to-v2 migration that adds a non-null translationStyle column with a default; NoteDatabase stores notes, tags, and their association in a separate version-1 database. These local examples show that schema and data ownership are app-specific. They do not prove every app has the same migration history or that any release has performed a production data migration. This guide is an engineering method, not a statement about a public app update. Keep three migrations distinct. A Room schema migration changes table structure and rows. A model/runtime migration changes the artifact or execution environment. A clean install or restore changes the app’s storage lifecycle. One may trigger another, but each needs separate compatibility and test evidence. For example, a translation row can gain a style field while its source and target text remain unchanged; a model variant switch does not by itself authorize rewriting the row. Derived output such as parsed fields, summaries, embeddings, or model annotations may depend on a model or parser revision and should be versioned separately from source history. Design the migration as an explicit, deterministic transformation. Define the old schema input and new schema output, whether a field receives a constant default or a derived value, how nulls and malformed legacy data are handled, and whether the change runs in a transaction. Keep the migration idempotency and rollback story clear: Room migration paths normally run once as the database advances, but an app may crash during startup or the database file may be copied/restored in another supported path. Test all supported starting versions to the current version; do not test only a freshly created database. If there is no safe automatic mapping, do not use destructive migration as a silent shortcut for a database that holds user content. Preserve provenance with the data. A row containing generated translation or analysis should state which values are original user input, which are model-derived, and—if implementation stores it—which artifact, prompt, or parser revision produced the derivative. If a schema field is renamed or split, keep source values and transform only fields with an unambiguous rule. If a derived field becomes incompatible with a new model, mark it stale, recompute only when the source is available and policy permits, or retain it with an explicit “not migrated” state. Do not falsely stamp old output as generated by the current model. Migration testing should use real exported schemas or fixture databases from each supported version. Verify primary keys, foreign keys, indexes, ordering, timestamps, favorites, tag relationships, and content. Include empty databases, rows with optional fields absent, unusual Unicode, large text, and records with unknown historical enum values. Add rollback or recovery tests that preserve an untouched copy before migration. Inspect the resulting schema with Room’s validation and test the DAO-level behavior, not only that opening the database no longer throws. Avoid placing actual customer content in committed fixtures; use synthetic examples with equivalent edge shapes. The user experience also needs explicit boundaries. A migration can take time or fail because of storage, schema, or corruption. Explain what is happening and whether the user’s source history is still available. Do not route a database migration failure to “download the model” unless evidence connects those systems. If there is a destructive fallback, it must be an explicit product decision, accurately disclosed, and tested to avoid accidental deletion. Backups and exports are separate destinations; successful Room migration does not prove the data was backed up or erased elsewhere. ### Procedure 1. Inventory database and schema history. Record database name, version, tables, constraints, indices, relations, and every supported old-to-current migration path. 2. Define a field mapping. Separate user-authored source records from generated derivatives and provenance; document defaults, conversions, malformed-value handling, and fields that must remain untouched. 3. Implement the migration transaction and preserve an untouched fixture copy. Use Room migrations for explicit schema transitions; do not silently destroy a user database to bypass a missing path. 4. Test each supported starting version, including populated, empty, sparse, malformed, and Unicode cases. Assert values and relations through DAOs after migration, not only schema opening. 5. Validate recovery and user messaging. Simulate interruption and migration failure, verify a recoverable source copy exists, and clearly distinguish database history from model/runtime setup. ### Acceptance criteria - Every supported old schema has a deterministic migration path and an explicit mapping for changed fields. - User-authored records and relationships survive migration; derived values preserve or invalidate provenance honestly. - Tests cover populated and edge-case fixtures across every supported schema version, including DAO-level reads and writes. - Migration failure does not silently erase user history or claim that model download, backup, or restore has succeeded. ### Comparison | Change type | Primary object | Required evidence | |---|---|---| | Room schema migration | Tables, rows, constraints, relations | Old/new schema fixture and data-preservation assertions | | Model/runtime migration | Artifact and execution stack | Model identity, runtime compatibility and rollback record | | Reinstall or restore | App storage lifecycle and backup paths | Fresh state, backup rules, restored files and user consent checks | ### FAQ **Is a Room migration the same as upgrading the model?** No. A database migration transforms stored records and schema; a model update changes artifact bytes or runtime configuration. If both happen in one app release, test and record each separately. **Can I use destructive migration to recover from a missing schema path?** Not silently for a database containing user records. Define an explicit recovery or export choice, preserve a source copy where possible, and disclose any data loss before it happens. **Should old model-generated output be relabeled with the new model version?** No. Preserve provenance honestly. Mark derived fields stale or unavailable, or recompute only under a documented rule from retained source data. **Is testing that the database opens enough?** No. Verify rows, keys, relationships, ordering and DAO behavior across populated fixtures from every supported old schema. Opening a fresh empty database misses migration defects.

A Room update adds or restructures local AI history fields

A team plans an app release that changes how translations and notes are stored. Existing users may have records from multiple old database versions, optional values, tags, and model-derived fields. The release must preserve authored content without attributing old output to a new model.

Decision

Migrate schema and data through explicit Room paths, keep user source separate from derived output and model provenance, and test every supported starting version.

Expected outcome

The app either migrates records deterministically or presents a recoverable state; it does not silently reset history or conflate database and model updates.

Evidence to collect

The claim becomes reviewable only when the following evidence is attached to the same artifact and test run:

• Old and new schema fixtures
• Migration transaction
• Rollback or recovery behavior

A completed byte stream is not enough. Final placement, integrity, runtime load, and recovery must also pass.

Implementation workflow

1. Map the database history. List each app-specific database, schema version, tables, fields, relations, indices, and the exact source version from which users can upgrade. Do not assume all Lens apps share one schema.
2. Specify source and derived mappings. Identify user-authored text, translated or analyzed output, tags, favorites, artifact references, and parser metadata. Define defaults and preserve unknown historical values instead of guessing.
3. Implement explicit Room paths. Write deterministic migrations for every supported version. Keep transformations transactional where appropriate and do not substitute a destructive reset for an unimplemented migration.
4. Test populated historical fixtures. Migrate real schema exports or synthetic equivalents from each supported version. Check keys, relations, timestamps, Unicode, missing fields, and unusual legacy values through DAOs.
5. Test recovery and disclose outcomes. Inject migration interruption and failure, retain a recoverable original fixture, and provide clear messaging that separates history recovery from model download or runtime setup.

Keep each transition observable. A failure should identify the stage, artifact, runtime, and recovery action without logging private user content.

Acceptance criteria

• Every supported starting schema has an explicit deterministic migration path.
• User content, keys, and relationships survive; derived output provenance is retained or clearly invalidated.
• Tests cover every supported version and DAO behavior with realistic populated edge fixtures.
• Migration failure never silently resets user history or claims unrelated model, backup, or restore success.

Decision table

Failure patterns to prevent

• Destructive in-place guesses
• Dropping artifact identity

Also prevent silent fallback, unpinned artifacts, missing cancellation, and conclusions that combine unlike configurations. Store unsuccessful runs alongside successful ones.

Minimum reproducibility record

Release checklist

• ☐ The primary query is answered without an unsupported number.
• ☐ Every artifact and runtime is pinned.
• ☐ The representative task and failure policy are explicit.
• ☐ Lifecycle, cancellation, cleanup, and fallback are tested.
• ☐ User-content and network boundaries are documented.
• ☐ Result wording applies only to the recorded configuration.
• ☐ The page links to raw method or evidence when results are added.

Sources and related evidence

• Android Room database migrations
• Android Room testing guide
• Android backup behavior and restore boundaries

Chinese deployment and troubleshooting content is organized in the .奇连 AI 端侧专题.

Frequently asked questions