StarPunk/docs/reports/v1.0.0-rc.1-hotfix-instructions.md

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:

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

# 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

-- Check current tokens table structure
PRAGMA table_info(tokens);
-- Should NOT have token_hash column

After Manual Fix (Option 1)

-- Verify column was added
PRAGMA table_info(tokens);
-- Should show token_hash column (even if temporary)

After Successful Deployment

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

# 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