Getting Started
Database troubleshooting
TurboPanel uses versioned SQL migrations in instance/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 Tilt, see Development architecture and instance/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 instance/src/lib/db/schema.ts |
| Fresh Postgres volume | Deno auto-pushes on startup when user table is missing; or run dev/scripts/sync.sh --force manually |
Connection failures
| Issue | What to do |
|---|---|
| Postgres unreachable | Check Tilt postgres resource; verify Docker is running |
| Wrong credentials | Check dev/.env POSTGRES_* vars; re-run env sync (tilt trigger env-sync or restart Tilt) |
| Connection pool wedged (Deno) | Restart the instance resource |
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:
# From dev/ with Postgres running
./scripts/sync.sh --force # after DROP SCHEMA public CASCADE; or use reset-dev APINuclear (dev only): stop Tilt, remove dev/.postgresql/ data directory, tilt up (recreates empty Postgres).
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.shto pull changes intoschema.ts. - Close Studio before running
dev/scripts/sync.shto avoid connection contention.
Do not run (current policy)
- Raw
drizzle-kit pushoutsidedev/scripts/sync.sh/dev/scripts/introspect.shworkflows (usedev/scripts/sync.shfor Deno dev push) - Applying or committing migration SQL without reviewing generated files under
migrations/
Manual debugging
# From dev/
./scripts/sync.sh --verbose
docker exec -it $(docker ps -qf name=postgres) psql -U turbopanel -d turbopanel -c '\dt'Related
Edit on GitHub
Last updated on