# v1.0.0-rc.1 Production Hotfix Instructions

## Critical Issue
v1.0.0-rc.1 fails to start on existing production databases with:
```
sqlite3.OperationalError: no such column: token_hash
```

## Root Cause
The database initialization tries to create an index on `token_hash` column before migrations run. The old `tokens` table doesn't have this column, causing immediate failure.

## Immediate Fix Options

### Option 1: Manual Database Preparation (Recommended)

**Before deploying v1.0.0-rc.1**, manually prepare the database:

```bash
# 1. Backup the database first
cp /path/to/starpunk.db /path/to/starpunk.db.backup

# 2. Connect to production database
sqlite3 /path/to/starpunk.db

# 3. Add the missing column temporarily
sqlite> ALTER TABLE tokens ADD COLUMN token_hash TEXT;
sqlite> .exit

# 4. Now deploy v1.0.0-rc.1
# Migration 002 will drop and properly recreate the tokens table
```

### Option 2: Code Hotfix

Modify `/app/starpunk/database.py` in the container:

1. Remove lines 58-60 (the index creation for tokens):
```python
# Comment out or remove these lines:
# CREATE INDEX IF NOT EXISTS idx_tokens_hash ON tokens(token_hash);
# CREATE INDEX IF NOT EXISTS idx_tokens_me ON tokens(me);
# CREATE INDEX IF NOT EXISTS idx_tokens_expires ON tokens(expires_at);
```

2. Let migration 002 create these indexes instead (it already does at lines 49-51)

### Option 3: Skip to v1.0.1

Wait for v1.0.1 release with proper fix, or build custom image with the fix.

## Verification Steps

### Before Deployment
```sql
-- Check current tokens table structure
PRAGMA table_info(tokens);
-- Should NOT have token_hash column
```

### After Manual Fix (Option 1)
```sql
-- Verify column was added
PRAGMA table_info(tokens);
-- Should show token_hash column (even if temporary)
```

### After Successful Deployment
```sql
-- Check migrations were applied
SELECT * FROM schema_migrations;
-- Should show 002_secure_tokens_and_authorization_codes.sql

-- Verify new table structure
PRAGMA table_info(tokens);
-- Should show proper structure with token_hash as required column

-- Verify indexes exist
SELECT name FROM sqlite_master WHERE type='index' AND tbl_name='tokens';
-- Should show idx_tokens_hash, idx_tokens_me, idx_tokens_expires
```

## Important Notes

1. **All existing tokens will be invalidated** - This is intentional for security
2. Users will need to re-authenticate after upgrade
3. The manual fix (Option 1) is temporary - migration 002 drops and recreates the table
4. Always backup the database before any manual intervention

## Recovery If Something Goes Wrong

```bash
# Restore from backup
mv /path/to/starpunk.db /path/to/starpunk.db.failed
cp /path/to/starpunk.db.backup /path/to/starpunk.db

# Revert to v0.9.5
docker pull ghcr.io/ai-christianson/starpunk:v0.9.5
docker run [...] ghcr.io/ai-christianson/starpunk:v0.9.5
```

## Long-term Solution

A proper architectural fix is being implemented for v1.1.0. See:
- ADR-031: Database Migration System Redesign
- Migration failure diagnosis report

## Contact

If you encounter issues with this hotfix, check:
- `/docs/reports/migration-failure-diagnosis-v1.0.0-rc.1.md`
- `/docs/decisions/ADR-031-database-migration-system-redesign.md`