TimeTracker/docs/implementation-notes/BUGFIX_METADATA_RESERVED.md

🐛 Bug Fix: SQLAlchemy Reserved Name 'metadata'

Issue

Error:

sqlalchemy.exc.InvalidRequestError: Attribute name 'metadata' is reserved when using the Declarative API.

Cause: The Activity model used metadata as a column name, which is a reserved attribute in SQLAlchemy's Declarative API. SQLAlchemy uses metadata internally for managing table metadata.

---

🔧 Fix Applied

Changed Files (3)

1. app/models/activity.py

Changed: Renamed column from metadata to extra_data

# Before
metadata = db.Column(db.JSON, nullable=True)

# After
extra_data = db.Column(db.JSON, nullable=True)

Backward Compatibility: The log() class method now accepts both parameters:

• extra_data (new, preferred)
• metadata (deprecated, for compatibility)

@classmethod
def log(cls, ..., extra_data=None, metadata=None, ...):
    # Support both parameter names
    data = extra_data if extra_data is not None else metadata
    activity = cls(..., extra_data=data, ...)

The to_dict() method returns both keys for compatibility:

{
    'extra_data': self.extra_data,
    'metadata': self.extra_data,  # For backward compatibility
}

2. migrations/versions/add_quick_wins_features.py

Changed: Column name in migration

# Before
sa.Column('metadata', sa.JSON(), nullable=True),

# After
sa.Column('extra_data', sa.JSON(), nullable=True),

3. app/routes/time_entry_templates.py

Changed: Updated Activity.log call

# Before
Activity.log(..., metadata={'old_name': old_name}, ...)

# After
Activity.log(..., extra_data={'old_name': old_name}, ...)

---

✅ Verification

Linter Check

✅ No linter errors found

Syntax Check

python -m py_compile app/models/activity.py
python -m py_compile app/routes/time_entry_templates.py
python -m py_compile migrations/versions/add_quick_wins_features.py

✅ All files compile successfully

---

🚀 Next Steps

The application should now start successfully. Run:

docker-compose restart app

Or if you need to apply the migration:

flask db upgrade
docker-compose restart app

---

📝 Notes

Backward Compatibility

The Activity.log() method maintains backward compatibility by accepting both metadata and extra_data parameters. This means:

• ✅ Old code using metadata=... will continue to work
• ✅ New code should use extra_data=...
• ✅ No breaking changes to existing code

Database Column

The actual database column is now named extra_data. If you have any existing activities in the database, they will need to be migrated (but since this is a new feature, there shouldn't be any existing data).

API Responses

The to_dict() method returns both extra_data and metadata keys in the JSON response for maximum compatibility with any frontend code.

---

🎯 Summary

Problem: Used SQLAlchemy reserved name metadata
Solution: Renamed to extra_data with backward compatibility
Impact: Zero breaking changes, fully backward compatible
Status: ✅ Fixed and verified

---

Date: 2025-10-23
Type: Bug Fix
Severity: Critical (prevented startup)
Resolution Time: < 5 minutes