Church-Music/legacy-site/documentation/md-files/MONGODB_MIGRATION_GUIDE.md

# 🚀 MongoDB Migration Guide

## Current Status

✅ **Preparation Complete:**

- MongoDB connection module created (`mongodb_models.py`)
- Migration script created (`migrate_to_mongodb.py`)
- Configuration files created (`.env`, `.env.example`)
- PyMongo package installed

## 📋 Two Options for MongoDB Setup

### Option 1: MongoDB Atlas (RECOMMENDED) ⭐

**Best for: Cross-device access (PC, mobile, tablet)**

**Pros:**

- ✅ Works from anywhere (cloud-hosted)
- ✅ Free forever (512MB M0 tier)
- ✅ No installation needed
- ✅ Automatic backups
- ✅ Always online (no need to keep PC running)
- ✅ Secure connections (TLS encryption)

**Setup Time:** 5-10 minutes

**Follow:** `MONGODB_ATLAS_SETUP.md` guide

**Steps Summary:**

1. Create free account at <https://www.mongodb.com/cloud/atlas/register>
2. Create M0 FREE cluster (choose AWS, closest region)
3. Create database user (save password!)
4. Allow network access (0.0.0.0/0 for all devices)
5. Get connection string
6. Update `backend/.env` with connection string
7. Run migration

---

### Option 2: Local MongoDB (PC Only)

**Best for: Testing locally, no internet needed**

**Pros:**

- ✅ Faster (local network)
- ✅ Full control
- ✅ No external dependencies

**Cons:**

- ❌ Only works on PC (mobile/tablet can't connect when PC is off)
- ❌ Requires installation
- ❌ PC must be running for access

**Setup Time:** 15-20 minutes

**Installation:**

1. Download MongoDB Community Server: <https://www.mongodb.com/try/download/community>
2. Run installer (choose "Complete" installation)
3. Install as Windows Service (keep defaults)
4. Verify installation:

   ```powershell
   mongod --version
   ```

5. Keep default `.env` settings (already configured for localhost)
6. Run migration

---

## 🎯 Recommended Path

**I recommend Option 1 (MongoDB Atlas)** because:

1. Your goal is "access across all platforms (PC, mobile, tablet)"
2. Cloud database works from anywhere
3. Free tier is perfect for this app size
4. No maintenance needed
5. Professional-grade hosting

## 📝 After You Choose

**Once you have MongoDB ready:**

### If MongoDB Atlas

```powershell
# 1. Edit backend/.env with your Atlas connection string
code backend\.env

# 2. Run migration
cd backend
.\venv\Scripts\python.exe migrate_to_mongodb.py

# 3. Verify data
# Check MongoDB Atlas dashboard → Browse Collections
```

### If Local MongoDB

```powershell
# 1. Verify MongoDB is running
Get-Service MongoDB

# 2. Run migration (uses localhost by default)
cd backend
.\venv\Scripts\python.exe migrate_to_mongodb.py

# 3. Verify data
# Use MongoDB Compass (free GUI) or mongo shell
```

## ⚡ Migration Will

1. ✅ Connect to MongoDB (Atlas or local)
2. ✅ Create collections with indexes
3. ✅ Copy all 39 songs from SQLite
4. ✅ Copy all 5 profiles from SQLite
5. ✅ Copy all 5 profile-song links from SQLite
6. ✅ Copy all 0 plans from SQLite
7. ✅ Verify all data migrated correctly
8. ✅ Show detailed migration report

**Migration is safe:**

- ✅ Does NOT delete SQLite data
- ✅ Does NOT modify existing files
- ✅ Skips duplicate records
- ✅ Can be run multiple times safely

## 🔄 Next Steps After Migration

Once migration succeeds, I'll:

1. Update `app.py` to use MongoDB instead of SQLite
2. Test all API endpoints
3. Verify frontend works with MongoDB
4. Clean up old SQLite code and files
5. Update documentation

## ❓ Questions?

**"Which should I choose?"**
→ MongoDB Atlas if you want mobile/tablet access
→ Local MongoDB only if PC-only is fine

**"Is it safe?"**
→ Yes! Your SQLite data stays unchanged. Migration only reads from it.

**"Can I switch later?"**
→ Yes! You can run migration again to different MongoDB instance.

**"What if migration fails?"**
→ Your original data is safe. We'll troubleshoot and try again.

## 🎬 Ready to Start?

**Tell me which option you prefer, and I'll guide you through the specific steps!**

**Option 1: MongoDB Atlas (cloud - recommended)**
**Option 2: Local MongoDB (PC only)**

Or if you have questions, ask away! 🚀