271 lines
7.0 KiB
Markdown
271 lines
7.0 KiB
Markdown
# 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. |