@redocly/replay 0.20.1 → 0.21.0-custom.0

package/README.md

@@ -1 +1,68 @@
 # Replay
+
+## Database Migrations
+
+The Replay app uses different database backends depending on the platform:
+- **Tauri (desktop)**: SQLite with Drizzle ORM
+- **Web**: IndexedDB with the `idb` library
+
+### SQLite Migrations (Tauri)
+
+SQLite schema is defined in `src/db/schema/` using Drizzle ORM. Migrations are auto-generated.
+
+**To add a migration:**
+
+1. Update the schema in `src/db/schema/` (e.g., `history.schema.ts`)
+2. Generate the migration from the `apps/replay-app` directory:
+   ```bash
+   pnpm db:generate
+   ```
+3. This creates a new `.sql` file in `apps/replay-app/src-tauri/migrations/` with a unique name
+4. Migrations run automatically on app startup via the Rust backend
+5. Alternatively, manually create a new migration file in `apps/replay-app/src-tauri/migrations/`:
+```bash
+# Format: YYYYMMDDHHMMSS_description.sql
+src-tauri/migrations/20241224120000_add_user_settings.sql
+```
+
+```sql
+-- Add new table
+CREATE TABLE IF NOT EXISTS user_settings (
+    id TEXT PRIMARY KEY NOT NULL,
+    key TEXT NOT NULL UNIQUE,
+    value TEXT NOT NULL
+);
+```
+
+### IndexedDB Migrations (Web)
+
+IndexedDB uses version-based migrations.
+
+**To add a migration:**
+
+1. Increment the version constant in the storage class (e.g., `HISTORY_DB_VERSION` in `HistoryIndexedDBStorage.ts`)
+2. Update the `setupDatabase()` method to handle both initial creation and upgrades:
+
+```typescript
+const HISTORY_DB_VERSION = 2; // Increment for new migration
+
+private static setupDatabase(db: IDBPDatabase<unknown>): void {
+  // Initial setup (runs for new databases)
+  if (!db.objectStoreNames.contains('history')) {
+    const store = db.createObjectStore('history', { keyPath: 'id' });
+    store.createIndex('by-date', 'date');
+  }
+
+  // Version 2: Add new index (runs on upgrade from v1)
+  const tx = db.transaction('history', 'readwrite');
+  const store = tx.objectStore('history');
+  if (!store.indexNames.contains('by-new-field')) {
+    store.createIndex('by-new-field', 'newField');
+  }
+}
+```
+
+**Best practices:**
+- Always check if stores/indexes exist before creating
+- Keep schema definitions in sync between SQLite and IndexedDB
+- Test migrations with existing data before release