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.