Phil Skentelbery
3ed77fd45f
Fixes critical issue where migration 002 indexes already existed in SCHEMA_SQL, causing 'index already exists' errors on databases created before v1.0.0-rc.1. Changes: - Removed duplicate index definitions from SCHEMA_SQL (database.py) - Enhanced migration system to detect and handle indexes properly - Added comprehensive documentation of the fix Version bumped to 1.0.0-rc.2 with full changelog entry. Refs: docs/reports/2025-11-24-migration-fix-v1.0.0-rc.2.md
111 lines
3.1 KiB
Markdown
111 lines
3.1 KiB
Markdown
# 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` |