petpicturequeue/README_MIGRATION.md

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:

# 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:

# 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)