RustBox/migrations/README.md

Database schemas and migrations

RustBox 0.1.1 has one database backend for the whole application:

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

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:

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.