v0.2.0

migrations/README.md

@@ -1,45 +1,40 @@
 # Database schemas and migrations
 
-RustBox 0.1.2 has one database backend for the whole application:
+RustBox 0.2.0 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
 ```
 
-When `session_backend = "database"`, sessions live in the same configured SQL database as the application data. `session_backend = "redis"` moves only session persistence to Redis; Redis Sentinel is a Redis discovery option and has no SQL schema.
+When `session_backend = "database"`, sessions live in the selected SQL database. `session_backend = "redis"` moves only session persistence to Redis/Redis Sentinel.
 
 ## Layout
 
 ```text
 migrations/
 ├── sqlite/
-│   └── schema.sql
+│   ├── schema.sql
+│   └── V047__blob_keys_and_search_outbox.sql
 ├── mysql/
-│   └── schema.sql
+│   ├── schema.sql
+│   └── V047__blob_keys_and_search_outbox.sql
 └── pgsql/
-    └── schema.sql
+    ├── schema.sql
+    └── V047__blob_keys_and_search_outbox.sql
 ```
 
-Every `schema.sql` is the complete schema for that engine. It contains:
+Each `schema.sql` is the current complete schema for fresh installations. The historical compatibility baseline remains **V046**. RustBox 0.2.0 adds **V047**, which adds attachment SHA-256 metadata and the durable search outbox used by external indexing.
 
-- global tables (`sessions`, `rustbox_accounts`), and
-- the full account-data baseline at schema version 46.
+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.
 
-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 the tenant part of each schema is replaced by RustBox at provisioning 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.
 
-## Future migrations
-
-The next application schema change is **V047**. A schema-changing release must add the same logical migration for every supported SQL engine, for example:
-
-```text
-migrations/sqlite/V047__description.sql
-migrations/mysql/V047__description.sql
-migrations/pgsql/V047__description.sql
-```
-
-Tenant migration SQL uses `{{p}}` for account tables. Register each new migration in the corresponding migration array in `src/db/pool.rs` and keep the version numbers aligned across all three engines. Do not edit `schema.sql` alone for an upgrade that must work on existing installations; update both the baseline and the versioned migration.
+The next migration number after RustBox 0.2.0 is **V048**.
 
 Redis and Redis Sentinel do not use SQL migrations.
 
@@ -49,3 +44,5 @@ Redis and Redis Sentinel do not use SQL migrations.
 - 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.

migrations/mysql/V047__blob_keys_and_search_outbox.sql

@@ -0,0 +1,18 @@
+ALTER TABLE {{p}}draft_attachments ADD COLUMN checksum_sha256 VARCHAR(64) NULL;
+
+CREATE TABLE {{p}}search_outbox (
+    id VARCHAR(64) PRIMARY KEY,
+    generation VARCHAR(64) NOT NULL,
+    event_type VARCHAR(16) NOT NULL,
+    message_uid BIGINT NOT NULL,
+    folder TEXT NOT NULL,
+    payload LONGTEXT NULL,
+    attempts BIGINT NOT NULL DEFAULT 0,
+    available_at BIGINT NOT NULL DEFAULT 0,
+    claimed_until BIGINT NOT NULL DEFAULT 0,
+    dead_letter BIGINT NOT NULL DEFAULT 0,
+    last_error TEXT NULL,
+    created_at BIGINT NOT NULL,
+    updated_at BIGINT NOT NULL,
+    INDEX idx_search_outbox_ready (dead_letter, available_at, claimed_until, updated_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

migrations/mysql/schema.sql

@@ -1,7 +1,7 @@
--- RustBox 0.1.2 MySQL schema.
+-- RustBox 0.2.0 MySQL schema.
 -- One physical database contains global sessions plus isolated per-account tables.
 -- Application tables are materialized by replacing {{p}} with a collision-checked prefix.
--- Baseline application schema version: 46. Future migrations start at V047.
+-- Squashed compatibility baseline: V046. Current runtime schema: V047.
 
 -- RUSTBOX:GLOBAL-BEGIN
 CREATE TABLE IF NOT EXISTS rustbox_accounts (
@@ -186,9 +186,27 @@ CREATE TABLE {{p}}draft_attachments (
     content_type TEXT NOT NULL,
     size BIGINT NOT NULL,
     file_path TEXT NOT NULL,
+    checksum_sha256 VARCHAR(64) NULL,
     created_at VARCHAR(64) NOT NULL DEFAULT (CAST(CURRENT_TIMESTAMP AS CHAR))
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
 
+CREATE TABLE {{p}}search_outbox (
+    id VARCHAR(64) PRIMARY KEY,
+    generation VARCHAR(64) NOT NULL,
+    event_type VARCHAR(16) NOT NULL,
+    message_uid BIGINT NOT NULL,
+    folder TEXT NOT NULL,
+    payload LONGTEXT NULL,
+    attempts BIGINT NOT NULL DEFAULT 0,
+    available_at BIGINT NOT NULL DEFAULT 0,
+    claimed_until BIGINT NOT NULL DEFAULT 0,
+    dead_letter BIGINT NOT NULL DEFAULT 0,
+    last_error TEXT NULL,
+    created_at BIGINT NOT NULL,
+    updated_at BIGINT NOT NULL,
+    INDEX idx_search_outbox_ready (dead_letter, available_at, claimed_until, updated_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
 CREATE TABLE {{p}}drafts (
     id VARCHAR(255) PRIMARY KEY,
     to_addresses LONGTEXT NOT NULL DEFAULT (''),

migrations/pgsql/V047__blob_keys_and_search_outbox.sql

@@ -0,0 +1,20 @@
+ALTER TABLE {{p}}draft_attachments ADD COLUMN checksum_sha256 TEXT;
+
+CREATE TABLE {{p}}search_outbox (
+    id TEXT PRIMARY KEY,
+    generation TEXT NOT NULL,
+    event_type TEXT NOT NULL,
+    message_uid BIGINT NOT NULL,
+    folder TEXT NOT NULL,
+    payload TEXT,
+    attempts BIGINT NOT NULL DEFAULT 0,
+    available_at BIGINT NOT NULL DEFAULT 0,
+    claimed_until BIGINT NOT NULL DEFAULT 0,
+    dead_letter BIGINT NOT NULL DEFAULT 0,
+    last_error TEXT,
+    created_at BIGINT NOT NULL,
+    updated_at BIGINT NOT NULL
+);
+
+CREATE INDEX {{p}}idx_search_outbox_ready
+    ON {{p}}search_outbox(dead_letter, available_at, claimed_until, updated_at);

migrations/pgsql/schema.sql

@@ -1,7 +1,7 @@
--- RustBox 0.1.2 PostgreSQL schema.
+-- RustBox 0.2.0 PostgreSQL schema.
 -- One physical database contains global sessions plus isolated per-account tables.
 -- Application tables are materialized by replacing {{p}} with a collision-checked prefix.
--- Baseline application schema version: 46. Future migrations start at V047.
+-- Squashed compatibility baseline: V046. Current runtime schema: V047.
 
 -- RUSTBOX:GLOBAL-BEGIN
 CREATE TABLE IF NOT EXISTS rustbox_accounts (
@@ -186,9 +186,28 @@ CREATE TABLE {{p}}draft_attachments (
     content_type TEXT NOT NULL,
     size BIGINT NOT NULL,
     file_path TEXT NOT NULL,
+    checksum_sha256 TEXT,
     created_at TEXT NOT NULL DEFAULT (CURRENT_TIMESTAMP::text)
 );
 
+CREATE TABLE {{p}}search_outbox (
+    id TEXT PRIMARY KEY,
+    generation TEXT NOT NULL,
+    event_type TEXT NOT NULL,
+    message_uid BIGINT NOT NULL,
+    folder TEXT NOT NULL,
+    payload TEXT,
+    attempts BIGINT NOT NULL DEFAULT 0,
+    available_at BIGINT NOT NULL DEFAULT 0,
+    claimed_until BIGINT NOT NULL DEFAULT 0,
+    dead_letter BIGINT NOT NULL DEFAULT 0,
+    last_error TEXT,
+    created_at BIGINT NOT NULL,
+    updated_at BIGINT NOT NULL
+);
+
+CREATE INDEX {{p}}idx_search_outbox_ready ON {{p}}search_outbox(dead_letter, available_at, claimed_until, updated_at);
+
 CREATE TABLE {{p}}drafts (
     id TEXT PRIMARY KEY,
     to_addresses TEXT NOT NULL DEFAULT '',

migrations/sqlite/V047__blob_keys_and_search_outbox.sql

@@ -0,0 +1,20 @@
+ALTER TABLE {{p}}draft_attachments ADD COLUMN checksum_sha256 TEXT;
+
+CREATE TABLE {{p}}search_outbox (
+    id TEXT PRIMARY KEY,
+    generation TEXT NOT NULL,
+    event_type TEXT NOT NULL,
+    message_uid INTEGER NOT NULL,
+    folder TEXT NOT NULL,
+    payload TEXT,
+    attempts INTEGER NOT NULL DEFAULT 0,
+    available_at INTEGER NOT NULL DEFAULT 0,
+    claimed_until INTEGER NOT NULL DEFAULT 0,
+    dead_letter INTEGER NOT NULL DEFAULT 0,
+    last_error TEXT,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+);
+
+CREATE INDEX {{p}}idx_search_outbox_ready
+    ON {{p}}search_outbox(dead_letter, available_at, claimed_until, updated_at);

migrations/sqlite/schema.sql

@@ -1,7 +1,7 @@
--- RustBox 0.1.2 SQLite schema.
+-- RustBox 0.2.0 SQLite schema.
 -- One physical database contains global sessions plus isolated per-account tables.
 -- Application tables are materialized from the tenant section by replacing {{p}}.
--- Baseline application schema version: 46. Future migrations start at V047.
+-- Squashed compatibility baseline: V046. Current runtime schema: V047.
 
 -- RUSTBOX:GLOBAL-BEGIN
 CREATE TABLE IF NOT EXISTS rustbox_accounts (
@@ -131,10 +131,29 @@ CREATE TABLE {{p}}draft_attachments (
     content_type TEXT NOT NULL,
     size INTEGER NOT NULL,
     file_path TEXT NOT NULL,
+    checksum_sha256 TEXT,
     created_at TEXT NOT NULL DEFAULT (datetime('now')),
     FOREIGN KEY (draft_id) REFERENCES {{p}}drafts(id) ON DELETE CASCADE
 );
 
+CREATE TABLE {{p}}search_outbox (
+    id TEXT PRIMARY KEY,
+    generation TEXT NOT NULL,
+    event_type TEXT NOT NULL,
+    message_uid INTEGER NOT NULL,
+    folder TEXT NOT NULL,
+    payload TEXT,
+    attempts INTEGER NOT NULL DEFAULT 0,
+    available_at INTEGER NOT NULL DEFAULT 0,
+    claimed_until INTEGER NOT NULL DEFAULT 0,
+    dead_letter INTEGER NOT NULL DEFAULT 0,
+    last_error TEXT,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+);
+
+CREATE INDEX {{p}}idx_search_outbox_ready ON {{p}}search_outbox(dead_letter, available_at, claimed_until, updated_at);
+
 CREATE TABLE {{p}}drafts (
     id TEXT PRIMARY KEY,
     to_addresses TEXT NOT NULL DEFAULT '',