Database Troubleshooting

Quick Checklist

• Confirm database.driver matches the deployed backend (postgres or sqlite).
• Run compozy migrate status to ensure schema migrations are current.
• Verify vector database configuration (mandatory for SQLite).
• Inspect logs for sql or database error codes—they surface context-specific hints.

PostgreSQL Issues

SQLite Issues

Vector Database Diagnostics

1. Verify vector database connectivity (qdrant --version, redis-cli ping, or file existence).
2. Confirm dimension matches the embedding model.
3. Check logs for provider-specific errors (e.g., HTTP 401 from Qdrant).

Diagnostic Commands

# Check migration status (driver auto-detected)
compozy migrate status

# Re-run migrations after configuration changes
compozy migrate up

# Verify PostgreSQL connectivity
psql "$COMPOZY_DB_CONN_STRING" -c 'SELECT version();'

# Inspect SQLite file
sqlite3 ./data/compozy.db ".tables"

Escalation Checklist

• Collect Compozy logs with --log-level=debug.
• Export relevant configuration snippet (redact secrets).
• Include output of compozy diagnose database (if feature flag enabled).
• Share vector database status (provider, endpoint, health).

Related Resources