Files

Phil Skentelbery f10d0679da feat(tags): Add database schema and tags module (v1.3.0 Phase 1)

Implements tag/category system backend following microformats2 p-category specification.

Database changes:
- Migration 008: Add tags and note_tags tables
- Normalized tag storage (case-insensitive lookup, display name preserved)
- Indexes for performance

New module:
- starpunk/tags.py: Tag management functions
  - normalize_tag: Normalize tag strings
  - get_or_create_tag: Get or create tag records
  - add_tags_to_note: Associate tags with notes (replaces existing)
  - get_note_tags: Retrieve note tags (alphabetically ordered)
  - get_tag_by_name: Lookup tag by normalized name
  - get_notes_by_tag: Get all notes with specific tag
  - parse_tag_input: Parse comma-separated tag input

Model updates:
- Note.tags property (lazy-loaded, prefer pre-loading in routes)
- Note.to_dict() add include_tags parameter

CRUD updates:
- create_note() accepts tags parameter
- update_note() accepts tags parameter (None = no change, [] = remove all)

Micropub integration:
- Pass tags to create_note() (tags already extracted by extract_tags())
- Return tags in q=source response

Per design doc: docs/design/v1.3.0/microformats-tags-design.md

Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>

2025-12-10 11:24:23 -07:00

3.1 KiB

Raw Blame History

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:

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

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

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

All existing tokens will be invalidated - This is intentional for security
Users will need to re-authenticate after upgrade
The manual fix (Option 1) is temporary - migration 002 drops and recreates the table
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

3.1 KiB Raw Blame History