add db migration

AGENTS.md

@@ -82,6 +82,17 @@ frontend/src/
 
 ## Database Schema
 
+**⚠️ IMPORTANT: Database Migrations**
+
+This project uses **Alembic** for database migrations. When modifying database schema:
+1. Never delete the database in production
+2. Always create migrations: `cd backend && ./migrate.sh create "description"`
+3. Review the generated migration in `alembic/versions/`
+4. Apply with: `./migrate.sh upgrade`
+5. See [MIGRATIONS.md](MIGRATIONS.md) for complete guide
+
+Migrations run automatically on app startup, so existing deployments will auto-upgrade.
+
 ### Tables
 
 **music**
@@ -286,10 +297,37 @@ docker-compose up -d
 
 ### Modifying Database Schema
 
+**IMPORTANT: We use Alembic for database migrations. Never delete the database in production!**
+
 1. **Update model in `backend/app/models/models.py`**
-2. **Update schema in `backend/app/schemas/schemas.py`**
-3. **Delete database** `rm data/youmusic.db` (recreates on restart)
-4. **Restart backend** to create new schema
+   ```python
+   class Music(Base):
+       # ... existing fields ...
+       new_field: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+   ```
+
+2. **Create migration**
+   ```bash
+   cd backend
+   ./migrate.sh create "Add new_field to music table"
+   ```
+
+3. **Review generated migration** in `backend/alembic/versions/*.py`
+   - Check auto-generated SQL is correct
+   - Edit if needed (e.g., for renaming columns, data migrations)
+
+4. **Apply migration**
+   ```bash
+   ./migrate.sh upgrade
+   ```
+
+5. **Update schema in `backend/app/schemas/schemas.py`** if needed
+
+**Notes:**
+- Migrations run automatically on app startup
+- Never edit applied migrations - create new ones
+- Use `./migrate.sh downgrade` to rollback if needed
+- See [MIGRATIONS.md](MIGRATIONS.md) for complete guide
 
 ### Adding Download Source
 
@@ -340,6 +378,7 @@ npm test
 - `uvicorn` - ASGI server
 - `sqlalchemy` - ORM
 - `aiosqlite` - Async SQLite driver
+- `alembic` - Database migrations
 - `yt-dlp` - Universal downloader
 - `mutagen` - Audio metadata
 - `pydantic` - Data validation