v0.1.1

migrations/README.md

@@ -0,0 +1,52 @@
+# Database schemas and migrations
+
+RustBox 0.1.1 has one database backend for the whole application:
+
+```text
+database_backend = sqlite | mysql | pgsql
+session_backend  = database | redis
+```
+
+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.
+
+## Layout
+
+```text
+migrations/
+├── sqlite/
+│   └── schema.sql
+├── mysql/
+│   └── schema.sql
+└── pgsql/
+    └── schema.sql
+```
+
+Every `schema.sql` is the complete schema for that engine. It contains:
+
+- 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 the tenant part of each schema is replaced by RustBox at provisioning time. Sessions are global and therefore are not prefixed.
+
+The SQLite baseline is structurally equivalent to the legacy V001-V046 migration chain. On first access, RustBox 0.1.1 imports an existing legacy `data_dir/<user_hash>/db.sqlite` at `PRAGMA user_version = 46` into the configured backend. Only after a successful import is the legacy file renamed to `db.sqlite.pre-0.1.1.bak`. Older legacy schemas must first be upgraded with RustBox 0.1.0.
+
+## 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.
+
+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.