# Database Migration Guide

## When to Migrate

If you're upgrading from a version of peon-mcp prior to v0.2.6 and encounter this error when creating tasks:

```
sqlite3.IntegrityError: CHECK constraint failed: status IN ('todo', 'in_progress', 'done', 'cancelled')
```

You need to run the migration script to update your database schema.

## How to Migrate

1. **Back up your database** (optional but recommended):
   ```bash
   cp ~/.peon/peon_tasks.db ~/.peon/peon_tasks.db.backup
   ```

2. **Run the migration**:
   ```bash
   peon-migrate
   ```

   Or if you haven't installed the package yet:
   ```bash
   uv run python -m peon_mcp.migrate_task_status
   ```

3. **Verify the migration**:
   The script will output:
   - `✓ Database already supports 'grooming' and 'timeout' statuses. No migration needed.` — if your database is already up to date
   - `✓ Migration completed successfully!` — if the migration was performed

## What Changed

The migration updates the `tasks` table CHECK constraint to support two new status values:
- `grooming` — for tasks still being defined or refined
- `timeout` — for tasks that exceeded their time limit

**Old constraint:**
```sql
CHECK(status IN ('todo', 'in_progress', 'done', 'cancelled'))
```

**New constraint:**
```sql
CHECK(status IN ('grooming', 'todo', 'in_progress', 'done', 'cancelled', 'timeout'))
```

## Troubleshooting

If the migration fails:

1. **Check permissions**: Ensure you have write access to your database file
2. **Close connections**: Stop any running `peon-ui` or `peon-mcp` processes
3. **Manual migration**: If the script fails, you can recreate the database:
   ```bash
   mv ~/.peon/peon_tasks.db ~/.peon/peon_tasks.db.old
   # The database will be recreated automatically on next use
   ```
   ⚠️ **Warning**: This will lose all existing data. Export your tasks first if needed.

## Future Migrations

For future schema changes, check this file and the `peon_mcp/` directory for migration scripts.
