# Database schemas and migrations

RustBox keeps SQL, blob storage and search as independent concerns.

```text
database_backend = sqlite | mysql | pgsql
session_backend  = database | redis
storage.backend  = filesystem | s3
search.backend   = disabled | local_tantivy | opensearch
```

## Layout

```text
migrations/
├── sqlite/schema.sql
├── mysql/schema.sql
└── pgsql/schema.sql
```

Each `schema.sql` is the complete V050 schema for fresh installations. Migrations V047-V049 have been consolidated into the **V049 compatibility baseline** and their standalone files are intentionally removed. V050 remains the single runtime migration. Because RustBox 0.2.15 has not been released yet, V050 includes `mail_preferences.compact_wide_rows`, `identities.signature_insert_mode`, `display_preferences.adaptive_email_colors` and `mail_preferences.message_loading_mode`.

`mail_preferences.message_loading_mode` defaults to `pagination`; `messages_per_page` defaults to 300. Supported modes are `pagination`, `progressive` and `all`.

Databases older than **V049** are no longer migrated directly by this build. Upgrade them to schema V049 first; this build then applies V050. **V051** is the next migration number after this snapshot.

Account data is isolated inside the selected physical database with a deterministic, collision-checked table prefix derived from the account hash. The `{{p}}` marker in tenant SQL is replaced by RustBox at provisioning time. Sessions are global and therefore are not prefixed.

## Runtime migrations

V050 is the only runtime migration in this unreleased snapshot. Future schema-changing releases must add the same logical migration for SQLite, MySQL and PostgreSQL and register it in `src/db/pool.rs`.

Redis and Redis Sentinel do not use SQL migrations.

## Engine notes

- SQLite uses `data_dir/rustbox.sqlite` by default; `database_url` may point to another persistent SQLite file.
- MySQL requires `database_url` and targets MySQL 8.0.13 or newer.
- PostgreSQL requires `database_url`.
- MySQL/PostgreSQL are full application backends, not session-only databases.
- The SQL engine does not choose blob/search storage. PostgreSQL/MySQL may still use local filesystem/Tantivy in single-node mode.
- Cluster mode requires a shared MySQL/PostgreSQL database plus cluster-safe blob/search choices; local `data_dir` is not inherently required.