breedr/docs/VERIFICATION_CHECKLIST.md

BREEDR Verification Checklist

Microchip Field Fix Verification

✅ Schema Files (All Correct)

1. Database Schema: server/db/init.js

• Line 29: microchip TEXT, (no UNIQUE constraint)
• Lines 38-43: Partial unique index created

  CREATE UNIQUE INDEX IF NOT EXISTS idx_dogs_microchip 
  ON dogs(microchip) 
  WHERE microchip IS NOT NULL
  

Status: ✅ Correct for future installations

---

2. UI Form: client/src/components/DogForm.jsx

• Line 150: Microchip input has NO required attribute
• Label shows "Microchip Number" (no asterisk)
• Field is truly optional in the UI

Status: ✅ Correct - users can leave microchip blank

---

3. Migration Script: server/db/migrate_microchip.js

• Exists and is executable
• Safely migrates existing databases
• Idempotent (can run multiple times)
• Preserves all data during migration

Status: ✅ Available for existing installations

---

4. Migration Helper: migrate-now.sh

• Shell script for easy execution
• Checks if container is running
• Runs migration inside container
• Restarts container after migration

Status: ✅ User-friendly migration tool

---

5. Documentation: docs/MICROCHIP_FIX.md

• Problem explanation
• Solution details
• Migration instructions (3 options)
• Verification tests
• Troubleshooting guide

Status: ✅ Complete documentation

---

6. README: README.md

• Migration notice at top
• Link to detailed documentation
• Upgrade instructions included
• Recent updates section added

Status: ✅ Users will see migration notice

---

For Future Installations

Fresh Install (No Migration Needed)

When a user does a fresh install (no existing database):

1. Container starts
2. server/db/init.js runs automatically
3. Database created with correct schema
4. Microchip field is optional from the start
5. No migration required ✅

Existing Installation (Migration Required)

When a user upgrades from an old version:

1. Pull latest code
2. Rebuild Docker image
3. Start container
4. Must run migration: docker exec -it breedr node server/db/migrate_microchip.js
5. Restart container
6. Microchip field now optional ✅

---

Testing Checklist

Test 1: Add Dog Without Microchip

curl -X POST http://localhost:3000/api/dogs \
  -H "Content-Type: application/json" \
  -d '{"name":"TestDog1","breed":"Lab","sex":"male"}'

Expected: ✅ Success (201 Created)

Test 2: Add Multiple Dogs Without Microchips

curl -X POST http://localhost:3000/api/dogs \
  -H "Content-Type: application/json" \
  -d '{"name":"TestDog2","breed":"Lab","sex":"female"}'

Expected: ✅ Success (multiple NULL values allowed)

Test 3: Add Dog With Microchip

curl -X POST http://localhost:3000/api/dogs \
  -H "Content-Type: application/json" \
  -d '{"name":"TestDog3","breed":"Lab","sex":"male","microchip":"123456789"}'

Expected: ✅ Success

Test 4: Duplicate Microchip Should Fail

curl -X POST http://localhost:3000/api/dogs \
  -H "Content-Type: application/json" \
  -d '{"name":"TestDog4","breed":"Lab","sex":"female","microchip":"123456789"}'

Expected: ❌ Error (UNIQUE constraint still enforced for non-NULL)

---

Database Verification

Check Schema Directly

# Enter container
docker exec -it breedr sh

# Open SQLite CLI
sqlite3 /app/data/breedr.db

# Check table schema
.schema dogs

# Should show:
# microchip TEXT,  (no UNIQUE)

# Check indexes
.indexes dogs

# Should show:
# idx_dogs_microchip (partial index)

# Verify partial index
SELECT sql FROM sqlite_master 
WHERE type='index' AND name='idx_dogs_microchip';

# Should show:
# CREATE UNIQUE INDEX idx_dogs_microchip 
# ON dogs(microchip) WHERE microchip IS NOT NULL

---

Rollback Plan

If something goes wrong:

Option A: Restore Backup

docker stop breedr
cp /mnt/user/appdata/breedr/breedr.db.backup \
   /mnt/user/appdata/breedr/breedr.db
docker start breedr

Option B: Re-run Migration

docker exec -it breedr node server/db/migrate_microchip.js
docker restart breedr

Option C: Fresh Database (Data Loss)

docker stop breedr
rm /mnt/user/appdata/breedr/breedr.db
docker start breedr

---

Deployment Verification

After deploying to production:

• Check container logs for schema initialization
• Verify database schema with SQLite CLI
• Test adding dog without microchip via UI
• Test adding dog with microchip via UI
• Confirm no UNIQUE constraint errors
• Verify partial index exists
• Test duplicate microchip still fails

---

Common Issues

Issue: Still Getting UNIQUE Constraint Error

Cause: Migration not run on existing database

Solution:

docker exec -it breedr node server/db/migrate_microchip.js
docker restart breedr

Issue: Migration Script Not Found

Cause: Old code still in container

Solution:

cd /mnt/user/appdata/breedr-build
git pull
docker build -t breedr:latest .
docker stop breedr && docker rm breedr
# Recreate container with new image

Issue: Microchip Required in UI

Cause: Browser cached old JavaScript

Solution:

• Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
• Clear browser cache
• Try incognito/private window

---

File Manifest

Core Files (Must Be Present)

• ✅ server/db/init.js - Database schema (corrected)
• ✅ server/db/migrate_microchip.js - Migration script
• ✅ client/src/components/DogForm.jsx - UI form (microchip optional)
• ✅ migrate-now.sh - Helper script
• ✅ docs/MICROCHIP_FIX.md - Detailed documentation
• ✅ docs/VERIFICATION_CHECKLIST.md - This file
• ✅ README.md - Updated with migration notice

Validation Commands

# Check all files exist
ls -la server/db/init.js
ls -la server/db/migrate_microchip.js
ls -la client/src/components/DogForm.jsx
ls -la migrate-now.sh
ls -la docs/MICROCHIP_FIX.md
ls -la docs/VERIFICATION_CHECKLIST.md

# Verify microchip field in init.js
grep -n "microchip TEXT" server/db/init.js
# Should show line 29 with NO UNIQUE

# Verify partial index
grep -A2 "idx_dogs_microchip" server/db/init.js
# Should show WHERE clause

# Verify form has no required
grep -n 'name="microchip"' client/src/components/DogForm.jsx
# Should NOT have required attribute

---

Sign-Off

Pre-Deployment Checklist

• Schema file correct (no UNIQUE on microchip)
• Partial index created (WHERE IS NOT NULL)
• UI form allows empty microchip
• Migration script tested
• Documentation complete
• README updated
• Tests passing

Post-Deployment Checklist

• Container started successfully
• Schema verified in database
• UI allows empty microchip
• Multiple NULL values work
• Unique constraint still enforced for non-NULL
• No errors in logs

---

Last Verified: March 8, 2026

Status: ✅ All files correct for future installations

Migration Required: Only for existing databases (one-time)