Migration & Upgrade Guide

This guide covers how to upgrade TBD Agents between versions, handle database migrations, and avoid common pitfalls.

---

General Upgrade Steps

1. Read the changelog — check the GitHub releases for breaking changes.
2. Back up your database — always snapshot MongoDB before upgrading.
3. Pull the new image or code — update your Docker image or git pull the latest tag.
4. Run database migrations — apply any schema changes (see below).
5. Restart services — restart the API server and Celery workers.

Docker Compose upgrade

# Pull latest images
docker compose pull

# Restart with the new version
docker compose down
docker compose up -d

Local development upgrade

git pull origin master
uv sync          # or: pip install -e ".[dev]"

---

Database Migrations

TBD Agents uses MongoDB with Beanie ODM. Beanie documents are schema-flexible — new fields with defaults are added automatically when existing documents are read. However, some changes require explicit migration.

When migration is NOT needed

• Adding a new field with a default value (Beanie populates it on read)
• Adding a new collection (Beanie creates it on first write)
• Adding new enum values to an existing enum field

When migration IS needed

• Renaming a field
• Changing a field's type
• Removing a field that is indexed
• Restructuring nested documents

Running a manual migration

For one-off migrations, use a Python script against the database:

"""Example: rename a field across all documents."""
import asyncio
from motor.motor_asyncio import AsyncIOMotorClient

async def migrate():
    client = AsyncIOMotorClient("mongodb://localhost:27017")
    db = client["tbd_agents"]

    # Rename 'old_field' to 'new_field' in the agents collection
    result = await db.agents.update_many(
        {"old_field": {"$exists": True}},
        {"$rename": {"old_field": "new_field"}},
    )
    print(f"Modified {result.modified_count} documents")
    client.close()

asyncio.run(migrate())

MongoDB backup / restore

# Backup
docker compose exec mongo mongodump --db tbd_agents --out /dump

# Restore
docker compose exec mongo mongorestore --db tbd_agents /dump/tbd_agents

---

Version-Specific Notes

v0.1.0 → v0.2.0

New features requiring attention:

Feature	Impact
Output guardrails	New output_config field on Guardrail documents. No migration needed — defaults to null.
SSE reconnection	Event bus now assigns monotonic event IDs. Clients can send Last-Event-ID header to replay missed events. No migration needed.
BYOK providers	New providers collection. No migration needed.
Knowledge sources	New knowledge_sources and knowledge_items collections plus GridFS buckets. No migration needed.
Agent memory	New memories collection. No migration needed.
MCP servers	New mcp_servers collection. No migration needed.

Environment variables added in v0.2.0:

Variable	Default	Description
REDIS_URL	redis://localhost:6379/0	Redis connection for event bus and caching
QDRANT_URL	—	Optional default Qdrant endpoint
GITHUB_CLIENT_ID	—	GitHub OAuth app client ID
GITHUB_CLIENT_SECRET	—	GitHub OAuth app client secret

Redis requirements:

v0.2.0 introduces Redis as a required dependency for SSE streaming and halt signals. Ensure Redis is running and REDIS_URL is configured.

---

Helm / Kubernetes Upgrades

If deploying via the Helm chart:

# Update chart values
helm upgrade tbd-agents ./helm/tbd-agents \
  --set image.tag=0.2.0 \
  --reuse-values

# Verify rollout
kubectl rollout status deployment/tbd-agents

StatefulSet changes

If the chart changes volume claims or StatefulSet specs, you may need to delete and recreate the StatefulSet. Check the chart changelog before upgrading.

---

Rollback

If an upgrade fails:

# Docker Compose — restore from backup
docker compose down
# Restore MongoDB from dump (see above)
docker compose up -d

# Helm — revert to previous release
helm rollback tbd-agents

---

Troubleshooting

Symptom	Likely Cause	Fix
ValidationError on startup	New required field without default	Run a migration script to backfill the field
SSE stream not connecting	Redis not running or URL misconfigured	Check REDIS_URL and verify Redis is reachable
Knowledge retrieval empty	Qdrant connection in error status	Call /api/knowledge-sources/<ID>/test and check last_error
Celery workers not starting	Mismatched package versions	Ensure API and workers run the same code version