Global Database 0.1

🎯 The objective

The aim of this milestone is to establish a production-ready, multiplatform foundation for Thunderbird for Android’s future global database.

Global Database 0.1 replaces the legacy per-account mail stores with one global mail database for the application. It keeps existing mail behavior, migrates durable mail data, and makes the global database the only mail source after validation.

The backend will be selected through a spike, which defines the resulting architecture and database foundation.

Success means that all production mail access uses the global database and every failed migration leaves legacy storage
unchanged and authoritative.

Schema-related changes are being addressed in Global Database 0.2.

🎒 Resources

• RFC 0007: Global Database
• Technical Design 0003: Global Database
• RFC 0008: Portable Profile Data Format
• Technical Design 0004: Portable Profile Data Format

🦮 Rules of the Road

🟢 In Scope

• Backend candidate selection through a Room 3 and SQLDelight spike that exercises the same representative mail, queue and full text search slice and compares against legacy.
• An RFC and technical design that records the selected direction, ownership boundaries, KMP platform requirements, migration safety, and verification strategy.
• A selected backend implementation with deterministic schema composition, coordinated migrations, transactions, and Android and JVM desktop support.
• A complete legacy-compatible global mail implementation covering every durable table, queued operation, and downloaded attachment in the migration inventory.
• A verified portable profile-data archive of locally available POP3 mail before migration. Its format, settings and profile data, import/export behavior, and full backup are defined by RFC 0008 . The same mail archive is available on request for IMAP accounts.
• Portable, sync-ready settings, account configuration, and account/profile data in the RFC 0008 representation.
• Repository pattern abstraction that cuts all mail reads, writes, sync, and background work to global storage after a successful migration.
• A migration design that reuses the existing Android database-migration activity or a suitable replacement for progress, failure feedback, retry, and local report export. Startup routing and background mail work must respect the migration gate.
• Verify the migration, restart recovery, and storage boundaries with automated tests.

🔴 Out of Scope

• Redesigning or normalizing the legacy mail schema or queue behavior beyond identifier changes.
• Moving account settings or profile runtime storage into the Global Database.
• Remote settings/profile synchronization transport, authentication, or replication.
• iOS and Web persistence support.
• Dual reads, dual writes, or a long-lived legacy compatibility source during the later cutover.
• Remote migration reporting, or changes to permissions, or OAuth.
• Introducing profiles or synchronization.

🚧 Technical and/or Business Requirements

• Public core and feature APIs must remain free of Room, SQLDelight, generated query/DAO, and feature-domain leakage, backend dependencies remain in internal modules.
• The database foundation must compose feature contributions deterministically and own one coordinated schema/migration history.
• The migration has one authoritative mail store at a time. Legacy storage remains authoritative until the durable cutover state is established. Global storage remains authoritative afterward.
• The migration reports non-sensitive phase and progress information and provides actionable failure feedback, retry, and local report export. Background work does not bypass the migration gate.
• A mail archive is created and verified before migration for POP3 accounts. A user may decline it after an explicit warning and continue at their own risk. It is available on request for IMAP accounts. Its format is defined by RFC 0008 and excludes credentials, tokens, queued operations, and internal database state.
• Public repository contracts follow the proposed ADR 0010. They do not expose persistence or legacy storage types.
• The shared mail schema, repository contracts, and attachment access support is KMP-ready for Android and JVM desktop. Legacy import is Android-only.
• Legacy sources are read-only. Validation covers data, relationships, queued operations, attachments, and search.
• Derived data, such as search indexes, is rebuilt during migration before validation runs.
• Copy each attachment to its target and validate it. If validation fails, record the failure in the migration result and fail the migration.
• Cutover removes legacy database and attachment artifacts. The legacy storage implementation stays in the codebase, unbound and unused, and a later release removes it.
• Reports and logs exclude personally identifiable data and are never uploaded

Updates

• (2026-07-22) The backend candidate selection spike in #11195 selected Room 3. Both candidates met the architectural baseline, but Room 3 delivered stronger response-time and concurrent-write results.