# Database

> Troubleshooting database connections, encoding, migration, and data persistence

- Skill: `kangarko/database` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kangarko/database`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kangarko/database/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kangarko (https://skillmd.com/u/kangarko)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/kangarko/database

---


# Database Troubleshooting

## Diagnostic Flow — "Database error / data lost"

1. Check `database.yml` Type/Host/Database/User/Password
2. For MySQL: database must exist (created manually), user needs full permissions
3. Check console for connection errors or slow warnings

## Common Mistakes

- **MySQL must use `utf8mb4_unicode_520_ci` collation** — other collations break unicode/emoji characters. Check `characterEncoding=UTF-8` in connection string
- **Connections >100ms are logged as warnings** — causes proxy server-switch delays. Co-locate MySQL server or switch to SQLite for single-server setups
- **`CLEAR_DATA_IF_INACTIVE` silently purges data** — players who haven't been online for the configured period lose all data (tags, channels, ignore lists, etc.). Users report "player data disappeared" — check this setting
- **Nick column is indexed for `/realname` lookups** — database-level optimization. Not user-facing but relevant for slow `/realname` queries
- **Migrator auto-migrates SQLite→MySQL on startup** — changing Type from `local` to `remote` triggers automatic migration. Monitor console for progress
- **Multiple PlayerCache entries = bug indicator** — if console logs warn about duplicate PlayerCache entries, it indicates a synchronization bug