Database troubleshooting

TurboPanel uses versioned SQL migrations in turbopanel/migrations/ (applied via pnpm migrate; tracked in public.migration). Deno dev can still use drizzle-kit push (dev/scripts/sync.sh) for quick schema iteration without committing migration files. For how schema sync fits into the dev environment, see Development architecture and turbopanel/src/lib/db/AGENTS.md in the repository.

Schema out of sync

Issue	What to do
API errors about missing columns/tables	From `dev/`: `./scripts/sync.sh` (or `./scripts/sync.sh --force` after editing `schema.ts`)
You changed the DB in Studio	Run `dev/scripts/introspect.sh` to pull live schema into `turbopanel/src/lib/db/schema.ts`
Fresh Postgres volume	Converge applies versioned migrations (`pnpm migrate` via `scripts/bootstrap-dev-db.sh`) — the only fresh-database bootstrap path. Re-run Developer → Converge / re-converge if relations are missing

Connection failures

Issue	What to do
Postgres unreachable	Check the `turbopanel-database` container (`docker ps` / Services area in `./console`); verify Docker is running
Wrong credentials	Postgres credentials are generated during converge under `/etc/turbopanel/`; re-run Developer → Converge / re-converge
Connection pool wedged (Deno)	`systemctl restart turbopanel-instance` (or restart it from the console Services area)

Reset dev database

Developer console (superadmin): /developer/database → Reset Dev Instance — drops public, re-pushes schema.ts, restarts instance. UI redirects through /recovering then /install or /sign-in.

Manual:

Terminal

# From dev/ with Postgres running
./scripts/sync.sh --force   # after DROP SCHEMA public CASCADE; or use reset-dev API

Nuclear (dev only): stop the instance (systemctl stop turbopanel-instance), remove the Postgres container and its data volume (docker rm -f turbopanel-database && docker volume rm turbopanel-database), then Developer → Converge / re-converge (recreates empty Postgres and applies migrations).

Drizzle Studio

Start from the developer console Database section.
Open https://local.drizzle.studio?host=localhost&port=4983.
Studio applies DDL directly — follow with dev/scripts/introspect.sh to pull changes into schema.ts.
Close Studio before running dev/scripts/sync.sh to avoid connection contention.

Do not run (current policy)

Raw drizzle-kit push outside dev/scripts/sync.sh / dev/scripts/introspect.sh workflows (use dev/scripts/sync.sh for Deno dev push)
Applying or committing migration SQL without reviewing generated files under migrations/

Manual debugging

Terminal

# From dev/
./scripts/sync.sh --verbose
docker exec -it turbopanel-database psql -U turbopanel -d turbopanel -c '\dt'

On this page