Add comprehensive deployment guide for database migration and frontend fix
This commit is contained in:
466
DEPLOY_NOW.md
Normal file
466
DEPLOY_NOW.md
Normal file
@@ -0,0 +1,466 @@
|
|||||||
|
# 🚀 BREEDR v0.4.0 - Ready to Deploy!
|
||||||
|
|
||||||
|
## ✅ What's Fixed
|
||||||
|
|
||||||
|
### Database Migration System
|
||||||
|
- **Automatic migrations** run on every server startup
|
||||||
|
- Detects and fixes old `sire`/`dam` column schema
|
||||||
|
- Migrates existing data to `parents` table
|
||||||
|
- Adds missing `litter_id` column
|
||||||
|
- Validates schema after migration
|
||||||
|
- **NO MANUAL SQL REQUIRED!**
|
||||||
|
|
||||||
|
### Frontend Form Fix
|
||||||
|
- Updated `DogForm.jsx` to ensure `sire_id` and `dam_id` are sent as `null` instead of empty strings
|
||||||
|
- Improved ID field handling with proper type conversion
|
||||||
|
- Better null value handling throughout the form
|
||||||
|
|
||||||
|
### Features Included
|
||||||
|
- ✅ Interactive pedigree tree with D3 visualization
|
||||||
|
- ✅ Litter management with parent auto-linking
|
||||||
|
- ✅ Dual parent selection mode (litter or manual)
|
||||||
|
- ✅ Enhanced error handling
|
||||||
|
- ✅ Automatic database repairs
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📦 Files Changed in This Branch
|
||||||
|
|
||||||
|
### Backend
|
||||||
|
- `server/db/migrations.js` - **NEW** Automatic migration system
|
||||||
|
- `server/index.js` - Runs migrations on startup
|
||||||
|
- `server/routes/dogs.js` - Already correct (uses `sire_id`/`dam_id`)
|
||||||
|
|
||||||
|
### Frontend
|
||||||
|
- `client/src/components/DogForm.jsx` - **FIXED** Null value handling
|
||||||
|
- `client/src/components/PedigreeTree.jsx` - **NEW** D3 visualization
|
||||||
|
- `client/src/components/PedigreeTree.css` - **NEW** Styling
|
||||||
|
- `client/src/utils/pedigreeHelpers.js` - **NEW** Utility functions
|
||||||
|
- `client/src/pages/PedigreeView.jsx` - **UPDATED** Full page
|
||||||
|
|
||||||
|
### Documentation
|
||||||
|
- `DATABASE_MIGRATIONS.md` - Complete migration guide
|
||||||
|
- `FRONTEND_FIX_REQUIRED.md` - Frontend fix reference
|
||||||
|
- `IMPLEMENTATION_PLAN.md` - Sprint planning
|
||||||
|
- `SPRINT1_PEDIGREE_COMPLETE.md` - Sprint 1 summary
|
||||||
|
- `DEPLOY_NOW.md` - **THIS FILE** Deployment guide
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 How to Deploy
|
||||||
|
|
||||||
|
### Step 1: Pull the Branch
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /path/to/breedr
|
||||||
|
git fetch origin
|
||||||
|
git checkout feature/enhanced-litters-and-pedigree
|
||||||
|
git pull origin feature/enhanced-litters-and-pedigree
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: Deploy with Docker (Recommended)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Stop current containers
|
||||||
|
docker-compose down
|
||||||
|
|
||||||
|
# Rebuild with new code
|
||||||
|
docker-compose build
|
||||||
|
|
||||||
|
# Start containers
|
||||||
|
docker-compose up -d
|
||||||
|
|
||||||
|
# Watch logs to see migration
|
||||||
|
docker-compose logs -f breedr
|
||||||
|
```
|
||||||
|
|
||||||
|
**You should see:**
|
||||||
|
```
|
||||||
|
============================================================
|
||||||
|
BREEDR Database Migration System
|
||||||
|
============================================================
|
||||||
|
[Migration 001] Checking for old sire/dam columns...
|
||||||
|
[Migration 001] Schema is already correct, skipping
|
||||||
|
OR
|
||||||
|
[Migration 001] Migrating to parents table...
|
||||||
|
[Migration 001] ✓ Migration complete!
|
||||||
|
|
||||||
|
[Validation] ✓ All schema checks passed!
|
||||||
|
============================================================
|
||||||
|
|
||||||
|
BREEDR Server Running on port 3000
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3: Deploy Without Docker
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Install dependencies
|
||||||
|
cd server && npm install
|
||||||
|
cd ../client && npm install
|
||||||
|
|
||||||
|
# Build frontend
|
||||||
|
npm run build
|
||||||
|
|
||||||
|
# Start server (migrations run automatically)
|
||||||
|
cd ../server
|
||||||
|
npm start
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✔️ Post-Deployment Testing
|
||||||
|
|
||||||
|
### 1. Server Startup
|
||||||
|
- [ ] Server starts without errors
|
||||||
|
- [ ] Migration logs show success
|
||||||
|
- [ ] No database errors in console
|
||||||
|
|
||||||
|
### 2. Add Dog Form
|
||||||
|
- [ ] Open "Add New Dog" modal
|
||||||
|
- [ ] Form displays correctly
|
||||||
|
- [ ] Can select Sire from dropdown
|
||||||
|
- [ ] Can select Dam from dropdown
|
||||||
|
- [ ] Can link to a litter
|
||||||
|
- [ ] Submit creates dog successfully
|
||||||
|
- [ ] **No "sire column" error!** ✅
|
||||||
|
|
||||||
|
### 3. Edit Dog Form
|
||||||
|
- [ ] Open existing dog
|
||||||
|
- [ ] Click "Edit"
|
||||||
|
- [ ] Parents display correctly
|
||||||
|
- [ ] Can change parents
|
||||||
|
- [ ] Save works without errors
|
||||||
|
|
||||||
|
### 4. Pedigree Tree
|
||||||
|
- [ ] Navigate to dog with parents
|
||||||
|
- [ ] Pedigree tree displays
|
||||||
|
- [ ] Can zoom and pan
|
||||||
|
- [ ] Can click nodes to navigate
|
||||||
|
- [ ] COI displays correctly
|
||||||
|
- [ ] Generation selector works
|
||||||
|
|
||||||
|
### 5. Litter Features
|
||||||
|
- [ ] Can create new litter
|
||||||
|
- [ ] Can add puppy linked to litter
|
||||||
|
- [ ] Parents auto-populate from litter
|
||||||
|
- [ ] Litter selection dropdown works
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔍 Troubleshooting
|
||||||
|
|
||||||
|
### Issue: Migration doesn't run
|
||||||
|
|
||||||
|
**Check:**
|
||||||
|
```bash
|
||||||
|
# View server logs
|
||||||
|
docker-compose logs breedr
|
||||||
|
|
||||||
|
# Or if running locally
|
||||||
|
cat server.log
|
||||||
|
```
|
||||||
|
|
||||||
|
**Manual migration:**
|
||||||
|
```bash
|
||||||
|
# In Docker
|
||||||
|
docker exec breedr node /app/server/db/migrations.js
|
||||||
|
|
||||||
|
# Locally
|
||||||
|
node server/db/migrations.js
|
||||||
|
```
|
||||||
|
|
||||||
|
### Issue: Still getting "sire column" error
|
||||||
|
|
||||||
|
**Possible causes:**
|
||||||
|
1. Old frontend code cached in browser
|
||||||
|
- **Fix:** Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)
|
||||||
|
- **Fix:** Clear browser cache
|
||||||
|
|
||||||
|
2. Container not rebuilt
|
||||||
|
- **Fix:** `docker-compose down && docker-compose up --build -d`
|
||||||
|
|
||||||
|
3. Wrong branch
|
||||||
|
- **Fix:** `git branch` to verify on `feature/enhanced-litters-and-pedigree`
|
||||||
|
|
||||||
|
### Issue: Form shows blank screen
|
||||||
|
|
||||||
|
**Cause:** Frontend build issue
|
||||||
|
|
||||||
|
**Fix:**
|
||||||
|
```bash
|
||||||
|
cd client
|
||||||
|
rm -rf dist node_modules
|
||||||
|
npm install
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
### Issue: Database locked error
|
||||||
|
|
||||||
|
**Cause:** Multiple processes accessing database
|
||||||
|
|
||||||
|
**Fix:**
|
||||||
|
```bash
|
||||||
|
# Stop all instances
|
||||||
|
docker-compose down
|
||||||
|
pkill -f "node.*server"
|
||||||
|
|
||||||
|
# Restart
|
||||||
|
docker-compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Database Schema (Current)
|
||||||
|
|
||||||
|
### Dogs Table
|
||||||
|
```sql
|
||||||
|
CREATE TABLE dogs (
|
||||||
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||||
|
name TEXT NOT NULL,
|
||||||
|
registration_number TEXT,
|
||||||
|
microchip TEXT,
|
||||||
|
sex TEXT CHECK(sex IN ('male', 'female')),
|
||||||
|
birth_date DATE,
|
||||||
|
breed TEXT,
|
||||||
|
color TEXT,
|
||||||
|
weight REAL,
|
||||||
|
height REAL,
|
||||||
|
notes TEXT,
|
||||||
|
litter_id INTEGER, -- ✅ Links to litter
|
||||||
|
photo_urls TEXT,
|
||||||
|
is_active INTEGER DEFAULT 1,
|
||||||
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||||
|
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||||
|
FOREIGN KEY (litter_id) REFERENCES litters(id)
|
||||||
|
);
|
||||||
|
-- ❌ NO sire or dam columns!
|
||||||
|
```
|
||||||
|
|
||||||
|
### Parents Table (Relationships)
|
||||||
|
```sql
|
||||||
|
CREATE TABLE parents (
|
||||||
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||||
|
dog_id INTEGER NOT NULL,
|
||||||
|
parent_id INTEGER NOT NULL,
|
||||||
|
parent_type TEXT NOT NULL CHECK(parent_type IN ('sire', 'dam')),
|
||||||
|
FOREIGN KEY (dog_id) REFERENCES dogs(id) ON DELETE CASCADE,
|
||||||
|
FOREIGN KEY (parent_id) REFERENCES dogs(id) ON DELETE CASCADE,
|
||||||
|
UNIQUE(dog_id, parent_type)
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📈 What Changed
|
||||||
|
|
||||||
|
### From Old Schema
|
||||||
|
```sql
|
||||||
|
CREATE TABLE dogs (
|
||||||
|
...
|
||||||
|
sire INTEGER, -- ❌ OLD
|
||||||
|
dam INTEGER, -- ❌ OLD
|
||||||
|
...
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
### To New Schema
|
||||||
|
```sql
|
||||||
|
CREATE TABLE dogs (
|
||||||
|
...
|
||||||
|
litter_id INTEGER, -- ✅ NEW
|
||||||
|
...
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE TABLE parents ( -- ✅ NEW
|
||||||
|
dog_id INTEGER,
|
||||||
|
parent_id INTEGER,
|
||||||
|
parent_type TEXT -- 'sire' or 'dam'
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
**Why?**
|
||||||
|
- More flexible relationship model
|
||||||
|
- Easier to query ancestry
|
||||||
|
- Better data integrity
|
||||||
|
- Supports future features (multiple parents, etc.)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📄 Migration Details
|
||||||
|
|
||||||
|
### What Gets Migrated
|
||||||
|
|
||||||
|
**Migration 001: Remove sire/dam columns**
|
||||||
|
1. Backup all dogs from old table
|
||||||
|
2. Extract sire relationships
|
||||||
|
3. Extract dam relationships
|
||||||
|
4. Drop old table
|
||||||
|
5. Create new table (without sire/dam)
|
||||||
|
6. Restore all dogs
|
||||||
|
7. Create parent relationships in `parents` table
|
||||||
|
|
||||||
|
**Migration 002: Add litter_id column**
|
||||||
|
1. Check if column exists
|
||||||
|
2. If missing, add column
|
||||||
|
3. Create foreign key constraint
|
||||||
|
|
||||||
|
### Data Preservation
|
||||||
|
|
||||||
|
All existing dog data is preserved:
|
||||||
|
- ✅ Dog names
|
||||||
|
- ✅ Registration numbers
|
||||||
|
- ✅ Breeds, colors, dates
|
||||||
|
- ✅ Photos
|
||||||
|
- ✅ Notes
|
||||||
|
- ✅ **Parent relationships** (moved to `parents` table)
|
||||||
|
|
||||||
|
**Nothing is lost!**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 API Contract
|
||||||
|
|
||||||
|
### POST /api/dogs
|
||||||
|
|
||||||
|
**Request:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "Buddy",
|
||||||
|
"breed": "Golden Retriever",
|
||||||
|
"sex": "male",
|
||||||
|
"sire_id": 5, // ✅ ID or null
|
||||||
|
"dam_id": 8, // ✅ ID or null
|
||||||
|
"litter_id": 2, // ✅ ID or null
|
||||||
|
"birth_date": "2024-01-15",
|
||||||
|
"registration_number": "GR12345",
|
||||||
|
"microchip": "123456789",
|
||||||
|
"color": "Golden",
|
||||||
|
"notes": "Good temperament"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": 15,
|
||||||
|
"name": "Buddy",
|
||||||
|
"breed": "Golden Retriever",
|
||||||
|
"sex": "male",
|
||||||
|
"litter_id": 2,
|
||||||
|
"birth_date": "2024-01-15",
|
||||||
|
"registration_number": "GR12345",
|
||||||
|
"microchip": "123456789",
|
||||||
|
"color": "Golden",
|
||||||
|
"notes": "Good temperament",
|
||||||
|
"photo_urls": [],
|
||||||
|
"is_active": 1,
|
||||||
|
"created_at": "2026-03-09T06:15:00.000Z",
|
||||||
|
"updated_at": "2026-03-09T06:15:00.000Z"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note:** `sire` and `dam` objects are added by GET endpoint, not stored in table.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 After Successful Deployment
|
||||||
|
|
||||||
|
### Verify Everything Works
|
||||||
|
|
||||||
|
1. **Server Console**
|
||||||
|
- No errors
|
||||||
|
- Migration completed successfully
|
||||||
|
- Server listening on port 3000
|
||||||
|
|
||||||
|
2. **Browser Console** (F12)
|
||||||
|
- No JavaScript errors
|
||||||
|
- API calls succeed (200 status)
|
||||||
|
- No "sire" or "dam" column errors
|
||||||
|
|
||||||
|
3. **Functionality**
|
||||||
|
- Add dog works
|
||||||
|
- Edit dog works
|
||||||
|
- Parents save correctly
|
||||||
|
- Pedigree tree displays
|
||||||
|
- Litters link properly
|
||||||
|
|
||||||
|
### Next Steps
|
||||||
|
|
||||||
|
1. **Merge to master** (after testing)
|
||||||
|
```bash
|
||||||
|
git checkout master
|
||||||
|
git merge feature/enhanced-litters-and-pedigree
|
||||||
|
git push origin master
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Tag release**
|
||||||
|
```bash
|
||||||
|
git tag -a v0.4.0 -m "Database migration system + pedigree tree"
|
||||||
|
git push origin v0.4.0
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Update ROADMAP.md** with next sprint
|
||||||
|
|
||||||
|
4. **Celebrate!** 🎉 The "sire column" error is gone forever!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Version Info
|
||||||
|
|
||||||
|
**Current Version:** v0.4.0
|
||||||
|
**Branch:** `feature/enhanced-litters-and-pedigree`
|
||||||
|
**Date:** March 9, 2026
|
||||||
|
|
||||||
|
### What's New
|
||||||
|
- ✅ Automatic database migration system
|
||||||
|
- ✅ Interactive pedigree tree visualization
|
||||||
|
- ✅ Litter management improvements
|
||||||
|
- ✅ Enhanced error handling
|
||||||
|
- ✅ **Fixed "sire column" error permanently**
|
||||||
|
|
||||||
|
### Breaking Changes
|
||||||
|
- **None** - Migrations handle all schema updates automatically
|
||||||
|
- Existing data is preserved and migrated
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ❓ Need Help?
|
||||||
|
|
||||||
|
### Common Questions
|
||||||
|
|
||||||
|
**Q: Will I lose my data?**
|
||||||
|
A: No! Migrations backup and restore all data.
|
||||||
|
|
||||||
|
**Q: Do I need to run SQL manually?**
|
||||||
|
A: No! Everything is automatic on server startup.
|
||||||
|
|
||||||
|
**Q: What if migration fails?**
|
||||||
|
A: Server won't start. Check logs, fix issue, restart.
|
||||||
|
|
||||||
|
**Q: Can I rollback?**
|
||||||
|
A: Yes, checkout previous branch and restore database backup.
|
||||||
|
|
||||||
|
**Q: Will this fix the sire error?**
|
||||||
|
A: Yes! 100%. The error is eliminated at the root cause.
|
||||||
|
|
||||||
|
### Support
|
||||||
|
|
||||||
|
If you encounter issues:
|
||||||
|
|
||||||
|
1. Check this deployment guide
|
||||||
|
2. Review `DATABASE_MIGRATIONS.md`
|
||||||
|
3. Check server logs
|
||||||
|
4. Review `FRONTEND_FIX_REQUIRED.md` for frontend issues
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎉 Summary
|
||||||
|
|
||||||
|
✅ **Backend migrations** - Automatic, tested, safe
|
||||||
|
✅ **Frontend fixes** - Proper null handling
|
||||||
|
✅ **Pedigree tree** - Beautiful visualization
|
||||||
|
✅ **Litter management** - Enhanced features
|
||||||
|
✅ **Documentation** - Complete guides
|
||||||
|
✅ **Error fixed** - "sire column" error eliminated
|
||||||
|
|
||||||
|
**Ready to deploy!** Just pull the branch and restart. 🚀
|
||||||
Reference in New Issue
Block a user