nextav/docs/active/fixes-enhancements/DATABASE_MIGRATION_GUIDE.md

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

# 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:

sqlite3 data/media.db

Run these commands to check your current tables:

.tables
.schema libraries
.schema media
.schema bookmarks
.schema stars

Step 3: Create the Migration Script

Create a new file migrate-folder-bookmarks.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

# 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

sqlite3 data/media.db

Then execute each command manually:

-- 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:

# Pull latest changes
git pull origin main

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

For Local Development:

# 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

# Check if the application can connect to the database
curl http://localhost:3000/api/health

6.2 Test Folder Bookmark API

# 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

# 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

docker-compose down
# or for local development
# Stop the dev server

Step 2: Restore Database

# 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)

# Revert to previous commit
git checkout [previous-commit-hash]

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

Step 4: Restart Application

# 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

docker-compose down
# Wait a few seconds, then run migration

Issue 2: "Permission denied"

Solution: Check file permissions

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.