nextav/docs/MIGRATION_README.md

📁 Folder Bookmarks Migration - Quick Start

This folder contains the migration tools to add folder bookmarking support to your existing NextAV instance.

🚀 Quick Migration (Recommended)

For Docker Deployments

# 1. Navigate to your NextAV directory
cd /path/to/your/nextav

# 2. Pull the latest code with folder bookmark support
git pull origin main

# 3. Run the automated migration script
docker exec -it nextav-nextav-1 /bin/sh -c "cd /app && ./scripts/migrate-folder-bookmarks.sh"

# 4. Restart the application
docker-compose down
docker-compose up -d

For Local Development

# 1. Navigate to your NextAV directory
cd /path/to/your/nextav

# 2. Pull the latest code
git pull origin main

# 3. Run the migration script
./scripts/migrate-folder-bookmarks.sh

# 4. Start the development server
pnpm dev

🔧 Manual Migration (Alternative)

If the automated script doesn't work for your setup, follow the manual process:

Step 1: Backup Your Database

# Create a backup
cp data/media.db data/media.db.backup-$(date +%Y%m%d-%H%M%S)

Step 2: Connect to Database

sqlite3 data/media.db

Step 3: Execute Migration SQL

-- Create 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 creation
.tables

Step 4: Exit and Restart

.quit

Then restart your application.

✅ Verification

After migration, verify everything works:

1. Check API endpoints:

   curl http://localhost:3000/api/folder-bookmarks
   curl http://localhost:3000/api/bookmarks
   

2. Test UI functionality:

   • Navigate to any folder in the folder viewer
   • Click the bookmark icon (should turn yellow)
   • Go to Bookmarks page
   • Verify folder bookmarks appear with folder icons

3. Test navigation:

   • Click on a folder bookmark
   • Verify it navigates to the correct folder

🔄 Rollback Instructions

If you need to rollback:

# 1. Stop the application
docker-compose down

# 2. Restore from backup
cp data/media.db.backup-[timestamp] data/media.db

# 3. Restart with previous code
git checkout [previous-commit-hash]
docker-compose up -d

📊 Migration Checklist

• Database backed up successfully
• Migration script executed without errors
• Application starts normally
• Folder bookmark API endpoints work
• UI shows bookmark buttons on folders
• Bookmarks page displays folder bookmarks
• Folder bookmark navigation works
• Existing media bookmarks still work

🆘 Troubleshooting

"Database is locked"

• Ensure the application is stopped during migration
• Wait a few moments and try again

"Permission denied"

chmod +x scripts/migrate-folder-bookmarks.sh
chmod 644 data/media.db

"Table already exists"

• This is normal - the migration handles existing tables gracefully

API endpoints return 404

• Ensure you restarted the application after code update
• Check application logs: docker logs nextav-nextav-1

📞 Support

If you encounter issues:

1. Check the detailed migration guide: docs/DATABASE_MIGRATION_GUIDE.md
2. Verify your backup: Ensure your backup file is valid
3. Check logs: Review application logs for error messages
4. Test manually: Use SQLite CLI to verify database state

📁 Files in This Directory

• DATABASE_MIGRATION_GUIDE.md - Detailed step-by-step migration guide
• MIGRATION_README.md - This quick start guide
• ../scripts/migrate-folder-bookmarks.sh - Automated migration script

---

🎉 Enjoy your new folder bookmarking feature!

You can now bookmark important folders alongside your media files for quick access to frequently used directories. 📁✨