# Geolocation Migration Quick Start

This is a quick reference guide for updating a running Thailand Water Monitor system to add geolocation support for Grafana geomap.

## 🚀 **Quick Migration (5 minutes)**

### **Step 1: Stop Application**
```bash
# Stop the service (choose your method)
sudo systemctl stop water-monitor
# OR
docker stop water-monitor
# OR use Ctrl+C if running manually
```

### **Step 2: Backup Database**
```bash
# SQLite backup
cp water_monitoring.db water_monitoring.db.backup

# PostgreSQL backup
pg_dump water_monitoring > backup.sql

# MySQL backup
mysqldump water_monitoring > backup.sql
```

### **Step 3: Run Migration**
```bash
# Run the automated migration script
python migrate_geolocation.py
```

### **Step 4: Restart Application**
```bash
# Restart the service
sudo systemctl start water-monitor
# OR
docker start water-monitor
# OR
python water_scraper_v3.py
```

## ✅ **Expected Output**
```
2025-07-28 17:30:00,123 - INFO - Starting geolocation column migration...
2025-07-28 17:30:00,124 - INFO - Detected database type: SQLITE
2025-07-28 17:30:00,127 - INFO - Added latitude column
2025-07-28 17:30:00,128 - INFO - Added longitude column
2025-07-28 17:30:00,129 - INFO - Added geohash column
2025-07-28 17:30:00,133 - INFO - ✅ Migration completed successfully!
```

## 🗺️ **Verify Geolocation Works**

### **Check Database**
```bash
# SQLite
sqlite3 water_monitoring.db "SELECT station_code, latitude, longitude, geohash FROM stations WHERE station_code = 'P.1';"

# Expected output: P.1|15.6944|100.2028|w5q6uuhvfcfp25
```

### **Test Application**
```bash
# Run a test cycle
python water_scraper_v3.py --test

# Should complete without errors
```

## 🔧 **Grafana Setup**

### **Query for Geomap**
```sql
SELECT 
    s.latitude, s.longitude, s.station_code, s.english_name,
    m.water_level, m.discharge_percent
FROM stations s 
JOIN water_measurements m ON s.id = m.station_id
WHERE s.latitude IS NOT NULL 
  AND m.timestamp = (SELECT MAX(timestamp) FROM water_measurements WHERE station_id = s.id)
```

### **Geomap Configuration**
1. Create new panel → Select "Geomap"
2. Set **Latitude field**: `latitude`
3. Set **Longitude field**: `longitude`
4. Set **Color field**: `water_level`
5. Set **Size field**: `discharge_percent`

## 🚨 **Troubleshooting**

### **Database Locked**
```bash
sudo systemctl stop water-monitor
pkill -f water_scraper
sleep 5
python migrate_geolocation.py
```

### **Permission Error**
```bash
sudo chown $USER:$USER water_monitoring.db
chmod 664 water_monitoring.db
```

### **Missing Dependencies**
```bash
pip install psycopg2-binary pymysql
```

## 🔄 **Rollback (if needed)**
```bash
# Stop application
sudo systemctl stop water-monitor

# Restore backup
cp water_monitoring.db.backup water_monitoring.db

# Restart
sudo systemctl start water-monitor
```

## 📚 **More Information**
- **Full Guide**: See `GEOLOCATION_GUIDE.md`
- **Migration Script**: `migrate_geolocation.py`
- **Database Schema**: Updated with latitude, longitude, geohash columns

## 🎯 **What You Get**
- ✅ **P.1 Station** ready for geomap (Nawarat Bridge)
- ✅ **Database Schema** updated for all 16 stations
- ✅ **Grafana Compatible** data structure
- ✅ **Backward Compatible** - existing data preserved

**Total Time**: ~5 minutes for complete migration