RustBox/migrations/README.md

Database schemas and migrations

RustBox 0.2.11 keeps SQL, blob storage and search as independent concerns:

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

When session_backend = "database", sessions live in the selected SQL database. session_backend = "redis" moves only session persistence to Redis/Redis Sentinel.

Layout

migrations/
├── sqlite/
│   ├── schema.sql
│   ├── V047__blob_keys_and_search_outbox.sql
│   └── V048__folder_counter_generation.sql
├── mysql/
│   ├── schema.sql
│   ├── V047__blob_keys_and_search_outbox.sql
│   └── V048__folder_counter_generation.sql
└── pgsql/
    ├── schema.sql
    ├── V047__blob_keys_and_search_outbox.sql
    └── V048__folder_counter_generation.sql

Each schema.sql is the current complete schema for fresh installations. The historical compatibility baseline remains V046. RustBox 0.2.1 adds V047, which adds attachment SHA-256 metadata and the durable search outbox used by external indexing. RustBox 0.2.8 adds V048, which adds the monotonic folders.counter_generation used to reject stale IMAP counter writes even when the numeric counts temporarily return to an earlier value.

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/migration time. Sessions are global and therefore are not prefixed.

Runtime migrations

Every schema-changing release must add the same logical migration for all supported SQL engines and register it in src/db/pool.rs. Do not update only schema.sql: fresh installs use the baseline while existing installations use the numbered migration path.

RustBox 0.2.11 does not add a runtime schema migration; V049 remains the next migration number.

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.