yurt

README_MIGRATION.md

@@ -0,0 +1,111 @@
+# 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)