# Database Migration Guide

## Session Changes Migration

During this development session, the following database changes were made:

### Changes Applied
1. **Added `likes` column** - INTEGER DEFAULT 0 (for the cookie-based like system)
2. **Ensured `description` column exists** - TEXT (for pet picture descriptions) 
3. **Verified `posted` column** - BOOLEAN DEFAULT 0 (for admin posting control)

### Migration Script

Run the migration script to update your database:

```bash
# Make sure you're in the project directory
cd /path/to/pet-picture-queue

# Activate virtual environment (if using one)
source .venv/bin/activate

# Run the migration
python migrate_session_changes.py
```

### What the Migration Does

The `migrate_session_changes.py` script:

- ✅ **Idempotent**: Safe to run multiple times
- ✅ **Backwards Compatible**: Won't break existing data
- ✅ **Verification**: Checks that migration completed successfully
- ✅ **Error Handling**: Proper error messages and rollback protection
- ✅ **Database Detection**: Automatically finds your database file

### Migration Output

You should see output like:
```
============================================================
Pet Picture Database Migration Script
Session Changes: Adding likes system and ensuring schema consistency
============================================================
Using database: pet_pictures.db
Starting database migration...
• Description column already exists
✓ Added likes column and initialized existing records
• Posted column already exists
✓ Cleaned up NULL values

Final table schema:
  id INTEGER NOT NULL 
  filename TEXT NOT NULL 
  subscriber_name TEXT NOT NULL 
  description TEXT NULL 
  uploaded_at TIMESTAMP NOT NULL 
  posted BOOLEAN NULL DEFAULT 0
  likes INTEGER NULL DEFAULT 0

Migration completed successfully!
Applied 1 migrations
Database contains X pet pictures
Migration completed at: 2025-01-XX...

============================================================
Verifying migration...
✅ Verification successful: All required columns present
🎉 Migration completed successfully!
============================================================
```

### Troubleshooting

**If migration fails:**
1. Check that the database file exists and is accessible
2. Ensure you have write permissions to the database file
3. Make sure no other process is using the database
4. Check the error message for specific issues

**If you need to start fresh:**
```bash
# Backup existing database (optional)
cp pet_pictures.db pet_pictures.db.backup

# Remove database and let app recreate it
rm pet_pictures.db

# Run the app - it will create a new database with correct schema
python main.py
```

### Schema After Migration

The final `pet_pictures` table schema:

| Column | Type | Constraints | Default | Description |
|--------|------|-------------|---------|-------------|
| id | INTEGER | PRIMARY KEY, AUTOINCREMENT | | Unique picture ID |
| filename | TEXT | NOT NULL | | Stored filename |
| subscriber_name | TEXT | NOT NULL | | Name of submitter |
| description | TEXT | | | Optional picture description |
| uploaded_at | TIMESTAMP | NOT NULL | | Upload timestamp |
| posted | BOOLEAN | | 0 | Admin approval status |
| likes | INTEGER | | 0 | Number of likes received |

### Files Created

- `migrate_session_changes.py` - Main migration script
- `README_MIGRATION.md` - This documentation
- `add_likes_column.py` - Individual likes column migration (deprecated, use main script)