# Database Migration Guide - Folder Bookmarks Feature

## Overview
This guide provides step-by-step instructions to safely update your existing NextAV database schema to support folder bookmarking without losing any existing data.

## ⚠️ Important Notes
- **Backup your database first** - Always create a backup before performing migrations
- **Test in staging** - If possible, test the migration on a staging environment first
- **Minimal downtime** - The migration adds a new table, so downtime should be minimal

## 🔧 Prerequisites

1. **Database Location**: Your database is typically located at:
   - Development: `./data/media.db`
   - Production: `/app/data/media.db` (inside Docker container)

2. **Backup Tools**: Ensure you have:
   - SQLite command-line tools installed
   - Access to your database file
   - Write permissions to the database directory

## 📋 Migration Steps

### Step 1: Create a Full Database Backup

```bash
# For local development
cp data/media.db data/media.db.backup-$(date +%Y%m%d-%H%M%S)

# For Docker deployment
docker cp nextav-nextav-1:/app/data/media.db ./media.db.backup-$(date +%Y%m%d-%H%M%S)
```

### Step 2: Verify Current Database Schema

Connect to your database and verify the current structure:

```bash
sqlite3 data/media.db
```

Run these commands to check your current tables:
```sql
.tables
.schema libraries
.schema media
.schema bookmarks
.schema stars
```

### Step 3: Create the Migration Script

Create a new file `migrate-folder-bookmarks.sql`:

```sql
-- Migration Script: Add Folder Bookmarks Support
-- Run this script to add folder bookmarking capability to existing NextAV databases

-- Step 1: Create the folder_bookmarks table
CREATE TABLE IF NOT EXISTS folder_bookmarks (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  folder_path TEXT NOT NULL UNIQUE,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Step 2: Create index for performance
CREATE INDEX IF NOT EXISTS idx_folder_bookmarks_path ON folder_bookmarks(folder_path);

-- Step 3: Verify the migration
SELECT name FROM sqlite_master WHERE type='table' AND name='folder_bookmarks';
SELECT sql FROM sqlite_master WHERE type='index' AND name='idx_folder_bookmarks_path';

-- Step 4: Test with a sample query
SELECT COUNT(*) as folder_bookmark_table_created FROM folder_bookmarks;
```

### Step 4: Execute the Migration

#### Option A: Direct SQLite Execution
```bash
# Run the migration script
sqlite3 data/media.db < migrate-folder-bookmarks.sql

# Verify the migration
sqlite3 data/media.db "SELECT name FROM sqlite_master WHERE type='table' AND name='folder_bookmarks';"
```

#### Option B: Manual Execution
```bash
sqlite3 data/media.db
```

Then execute each command manually:
```sql
-- Create the folder_bookmarks table
CREATE TABLE IF NOT EXISTS folder_bookmarks (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  folder_path TEXT NOT NULL UNIQUE,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Create index for performance
CREATE INDEX IF NOT EXISTS idx_folder_bookmarks_path ON folder_bookmarks(folder_path);

-- Verify the table was created
.tables

-- Exit SQLite
.quit
```

### Step 5: Update Application Code

The application code changes are already implemented in the codebase. You just need to:

1. **Pull the latest code** with folder bookmark support
2. **Restart your application** to load the new code

#### For Docker Deployment:
```bash
# Pull latest changes
git pull origin main

# Rebuild and restart
docker-compose down
docker-compose up --build -d
```

#### For Local Development:
```bash
# Pull latest changes
git pull origin main

# Install dependencies
pnpm install

# Build the application
pnpm build

# Start the development server
pnpm dev
```

### Step 6: Verify the Migration

#### 6.1 Test Database Connectivity
```bash
# Check if the application can connect to the database
curl http://localhost:3000/api/health
```

#### 6.2 Test Folder Bookmark API
```bash
# Test folder bookmark creation
curl -X POST "http://localhost:3000/api/folder-bookmarks/test-folder-path" \
  -H "Content-Type: application/json"

# Test folder bookmark retrieval
curl "http://localhost:3000/api/folder-bookmarks"
```

#### 6.3 Test Combined Bookmarks
```bash
# Check that your existing bookmarks still work
curl "http://localhost:3000/api/bookmarks"
```

### Step 7: Functional Testing

1. **Navigate to folder viewer** and verify bookmark buttons appear
2. **Bookmark a folder** and check that the icon changes
3. **Go to bookmarks page** and verify folder bookmarks appear
4. **Click a folder bookmark** and verify navigation works
5. **Unbookmark a folder** and verify it disappears from bookmarks

## 🔄 Rollback Procedure

If you need to rollback the migration:

### Step 1: Stop the Application
```bash
docker-compose down
# or for local development
# Stop the dev server
```

### Step 2: Restore Database
```bash
# Restore from backup
cp data/media.db.backup-[timestamp] data/media.db

# For Docker
docker cp ./media.db.backup-[timestamp] nextav-nextav-1:/app/data/media.db
```

### Step 3: Revert Code (if needed)
```bash
# Revert to previous commit
git checkout [previous-commit-hash]

# Or reset to previous state
git reset --hard [previous-commit-hash]
```

### Step 4: Restart Application
```bash
# Restart with restored database
docker-compose up -d
# or for local development
pnpm dev
```

## 📊 Verification Checklist

After migration, verify:

- [ ] Database backup created successfully
- [ ] `folder_bookmarks` table exists in database
- [ ] Index `idx_folder_bookmarks_path` created
- [ ] Application starts without errors
- [ ] Existing media bookmarks still work
- [ ] Folder bookmark API endpoints respond
- [ ] Folder bookmark UI appears in folder viewer
- [ ] Current folder bookmark button works
- [ ] Bookmarks page shows both media and folder bookmarks
- [ ] Clicking folder bookmarks navigates correctly

## 🐛 Common Issues and Solutions

### Issue 1: "Database is locked"
**Solution**: Ensure the application is stopped before migration
```bash
docker-compose down
# Wait a few seconds, then run migration
```

### Issue 2: "Permission denied"
**Solution**: Check file permissions
```bash
chmod 644 data/media.db
chown [your-user]:[your-group] data/media.db
```

### Issue 3: "Table already exists"
**Solution**: This is fine - the `IF NOT EXISTS` clause handles this

### Issue 4: API endpoints return 404
**Solution**: Ensure the application was restarted after code update

## 📞 Support

If you encounter issues:

1. Check the application logs: `docker logs nextav-nextav-1`
2. Verify database schema: `sqlite3 data/media.db ".schema"`
3. Test API endpoints manually with curl
4. Check browser console for frontend errors

## 📝 Migration Record

After successful migration, record:
- Migration date and time
- Database backup location
- Any issues encountered and solutions
- Performance observations

---

**Note**: This migration is designed to be non-destructive. The new folder bookmarks functionality is additive and doesn't modify existing data structures.