Database Troubleshooting
Overview
This playbook covers slow queries, missing data, duplicate data, and migration-related issues.
Why It Matters
Many incidents or bugs trace back to data shape, query cost, or migration safety.
Core Concepts
- Check the data first.
- Check the query shape.
- Check the migration or write path.
Mental Models
If the data looks wrong, ask whether it was written wrong, queried wrong, or cached wrong.
Best Practices
- Reproduce with a simple query.
- Inspect row counts and filters.
- Use constraints and transactions where needed.
Common Mistakes
- Blaming the UI for bad data.
- Running expensive queries blindly.
- Ignoring rollback safety in migrations.
Trade-offs
More safeguards slow some changes, but they reduce the chance of corrupt or inconsistent data.
Decision Framework
| Symptom | Check |
|---|---|
| Missing data | Writes, filters, cache |
| Slow data | Query plan and indexes |
| Duplicate data | Constraints and idempotency |
Examples
- Add a unique constraint instead of only checking in app code.
Checklists
- Is the query bounded?
- Are constraints protecting the data?
- Is the migration safe to roll back?
Senior Engineer Notes
Senior engineers treat data correctness as a product quality issue, not just a backend detail.