# RustBox database schema and migrations

RustBox keeps one complete fresh-install schema per supported SQL backend:

- `sqlite/schema.sql`
- `mysql/schema.sql`
- `pgsql/schema.sql`

## Compatibility baseline

The consolidated compatibility baseline is **V052** (RustBox 0.2.23). Historical migrations up to and including V052 are already represented by the complete `schema.sql` files and are intentionally not shipped as standalone runtime migrations in this source tree:

- V047-V050 — attachment/search-outbox changes, folder counter generation, blob deletion outbox, compact-row and signature preferences (consolidated in 0.2.16);
- V051 — `display_preferences.adaptive_email_colors` (default `0`) and `mail_preferences.message_loading_mode` (default `pagination`);
- V052 — the `snoozed_messages` table used by Snooze (local cache state only, no IMAP side effects, no foreign keys).

Databases older than V052 must first be upgraded with a RustBox release that can reach V052. RustBox 0.2.22 accepts V050 and V051 databases and migrates them to V052, so a tenant that has not logged in since an older release should be opened once with 0.2.22 before upgrading. Tenants below the baseline are refused with an explicit error instead of being partially migrated.

The MySQL fresh schema now declares `mail_preferences.message_loading_mode` with an expression default (`DEFAULT ('pagination')`); MySQL rejects literal defaults on `TEXT` columns.

## V053 — RustBox 0.2.23

V053 adds two appearance columns to `display_preferences`.

`skin_depth`, default `standard`, controls how far a predefined interface style may reshape the interface:

- `colors` — only the style's palette is applied; layout, shapes and typography come from your own appearance settings;
- `standard` — palette plus the style's fixed layout preferences (the behavior of earlier releases);
- `immersive` — additionally applies the style's structural design tokens: typography, control and avatar shapes, floating panes, app-bar treatment, selection markers and backdrop.

`skin_gradients`, default `0` / off, is a separate switch for every gradient a style uses (backdrops, app bars, buttons, Roundcube Classic bevels). When off, each style falls back to flat colors defined next to its gradient.

Fresh installations already contain both columns in `schema.sql` and are registered at the latest schema version. Existing V052 tenants execute `V053__skin_depth_and_gradients.sql`.

## V054 — RustBox 0.2.24

V054 adds three appearance columns to `display_preferences` and calendar reminder columns:

- `theme_light_from` / `theme_dark_from`, defaults `07:00` / `19:00` (`HH:MM`, local time of the browser) — used when `theme = 'schedule'`: light between the two times, dark otherwise (the window may wrap past midnight);
- `account_color`, default empty — an optional per-account colour shown as a stripe on the app bar and a dot next to the account address;
- `calendar_events.reminder_extra_minutes` (nullable) — an optional second reminder per event, e.g. one day before;
- `calendar_settings.default_reminder_minutes` / `default_extra_reminder_minutes` (nullable) — reminders pre-selected for new events.

Fresh installations already contain the columns in `schema.sql`. Existing V053 tenants execute `V054__theme_schedule_account_color_and_reminders.sql`.

## V055 — CalDAV / CardDAV

V055 prepares the calendar and contacts tables for the optional CalDAV/CardDAV server (`[dav]`):

- `calendar_events.dav_name` / `contacts.dav_name` (nullable) — resource name chosen by the DAV client (e.g. `4f9e….ics`); rows created in the webmail keep `NULL` and are served as `<id>.ics` / `<id>.vcf`;
- `calendar_events.dav_data` / `contacts.dav_data` (nullable) — the iCalendar object / vCard exactly as uploaded, so time zones, recurrence exceptions, alarms and vendor properties survive; webmail edits are patched into it;
- `idx_contacts_email` becomes a regular (non-unique) index, because an address book may contain several cards with the same address (and cards without any address);
- new indexes `idx_calendar_events_dav_name` and `idx_contacts_dav_name`.

Fresh installations already contain the columns in `schema.sql`. Existing V054 tenants execute `V055__caldav_carddav.sql`.

The next migration number is **V056**.

## Migration rules

Any future schema-changing release must:

1. update all three complete `schema.sql` files;
2. add the same logical numbered migration for SQLite, MySQL and PostgreSQL;
3. register that migration in `src/db/pool.rs`;
4. extend the offline migration tests in `scripts/validate-release-static.py`.

On MySQL, `TEXT` columns must use expression defaults such as `DEFAULT ('value')`.