An open-source web GUI for pg_timetable — the advanced PostgreSQL job scheduler by CYBERTEC.
pg_timetable is powerful, fully database-driven, and battle-tested — but it ships without a graphical interface. pg_timetable Studio fills that gap: a single static Go binary with an embedded web UI that lets you manage many pg_timetable installations, build and visualize chains, operate jobs (run / stop / pause), watch workers live, and search the execution history across all your databases — no psql required.
It talks to pg_timetable's own timetable schema directly over SQL. Nothing proprietary, nothing hidden — point it at a database a worker has initialized and it just works.
- Multi-installation registry — register and switch between any number of installations (prod, staging, per-customer…). Target DSNs are encrypted at rest (AES-256-GCM); connections are validated before they're saved.
- Dashboard — live chains, 24h runs/failures, success rate, workers online, an executions timeline, tasks-by-kind, and top failing chains.
- Chains — searchable, paginated list; a pipeline visualization; a form-based chain builder (no
psql) with typed parameter forms for the built-in tasks and live cron/@every/@rebootschedule validation against the target's owntimetable.crondomain. SQL steps use a CodeMirror editor with PostgreSQL syntax highlighting and live, in-browser syntax checking (the reallibpg_querygrammar compiled to WebAssembly). - Run history & flow graph — per chain, a timeline of recent runs plus a flow graph of the whole chain: runs flow down the success spine and divert to a stopped /
on_errorlane at each failing step, annotated with how often each path succeeded vs failed. Click any run to trace the exact path it took. - Failure alerting — a background poller records every chain failure to an in-app feed and can push new failures to webhook or Slack channels.
- Runs & logs — filter executions by chain, status, time range, and full-text; per-step detail; a click-to-expand command viewer; worker log viewer.
- Live — see what each worker is doing right now: running chains, recent executions (filterable + capped so a busy worker never overloads the browser), and recent worker logs.
- Operate — run / stop / pause-resume chains, RBAC-gated and audited.
- Search — unified search across executions, worker logs, and the GUI audit, across all installations, with CSV export and saved searches.
- Diagnose — a "why didn't it run / why did it fail?" doctor.
- AI assistant (optional) — explain a failed run in plain language, grounded in pg_timetable's model. Works against any OpenAI-compatible chat-completions endpoint (e.g. a self-hosted model); disabled and hidden when no key is configured. See AI assistant.
- Auth & RBAC — local users with Viewer / Operator / Admin roles, plus per-installation grants that elevate a user on specific installations. Server-side sessions; login throttling.
- Polish — light / dark / auto theme, and a UI translated into English, Spanish, German, Hindi, and Ukrainian.
Chain run-history flow graph — every run over time, and the whole chain rendered as a graph: how many runs flowed down each path, and where they failed.
Chain builder with a PostgreSQL editor — syntax highlighting and live validation against the real libpg_query grammar, right in the browser.
Failure alerting — a feed of every chain failure across installations, plus optional webhook / Slack delivery.
Runs and live worker activity, filterable and drill-downable.
One command brings up PostgreSQL + a pg_timetable worker + seeded sample chains + Studio:
docker compose up --build # then open http://localhost:8088Log in with admin@example.com / changeme (set via PGTT_GUI_ADMIN_*). docker compose down -v removes everything.
Pre-built, multi-architecture images (linux/amd64 and linux/arm64) are published to the GitHub Container Registry — :main tracks the latest commit on main, and tagged releases also publish :X.Y.Z and :latest:
docker run -p 8080:8080 \
-e PGTT_GUI_CONTROL_DSN="postgres://user:pass@host:5432/db?sslmode=disable" \
-e PGTT_GUI_SECRET="$(openssl rand -hex 32)" \
-e PGTT_GUI_ADMIN_EMAIL=admin@example.com \
-e PGTT_GUI_ADMIN_PASSWORD=change-me \
ghcr.io/cybertec-postgresql/gui_pg_timetable:mainThe control database (PGTT_GUI_CONTROL_DSN) is where Studio stores its own state — the registry of installations, users, sessions, and audit, in a timetable_gui schema. It can be any PostgreSQL; it does not have to be one that runs pg_timetable.
All configuration is via environment variables (see .env.example):
| Variable | Default | Description |
|---|---|---|
ADDR |
:8080 |
HTTP listen address. |
PGTT_GUI_CONTROL_DSN |
— | Required. DSN of the control database (hosts the timetable_gui schema). |
PGTT_GUI_SECRET |
— | Required. Secret used to derive the AES-256-GCM key that encrypts stored target DSNs. Use a long random value; losing it means re-entering installation credentials. |
PGTT_GUI_ADMIN_EMAIL |
— | Optional. If set (with the password) and no users exist yet, seeds the first admin on startup. Otherwise create it via POST /api/auth/setup. |
PGTT_GUI_ADMIN_PASSWORD |
— | Optional. Password for the seeded first admin. |
AUTH_SESSION_TTL_HOURS |
12 |
Server-side session lifetime. |
AUTH_COOKIE_SECURE |
false |
Set the Secure flag on the session cookie (enable behind TLS; also turns on HSTS). |
FRONTEND_DIST |
— | Optional. Serve a frontend build from disk instead of the embedded one (dev). |
PGTT_GUI_LLM_BASE_URL |
— | Optional. OpenAI-compatible chat-completions base URL for the AI assistant. |
PGTT_GUI_LLM_MODEL |
— | Optional. Model id to request. |
PGTT_GUI_LLM_KEY |
— | Optional. Bearer token for the gateway. Falls back to CYBERTEC_LLM_KEY. No key → AI features are disabled and hidden. |
Studio's AI features call an OpenAI-compatible /chat/completions endpoint — bring your own gateway (a self-hosted model, a corporate proxy, or any compatible service). It is off by default: with no key configured, the endpoints return 503 and the UI hides every AI affordance, so the open-source app runs fully without it.
-e PGTT_GUI_LLM_BASE_URL=https://your-gateway.example.com/v1 \
-e PGTT_GUI_LLM_MODEL=your-model \
-e PGTT_GUI_LLM_KEY=your-tokenThe first feature is Explain a failure (Runs tab → ✨ on a failed row): the server re-fetches the real execution row, grounds the model in pg_timetable's domain model, and returns a plain-language diagnosis + suggested fix. The model only ever proposes — it never writes to your databases.
Requires Go 1.26+, Node 20+, and Docker (for the test/dev harness).
make dev-up # Postgres + worker + seeded chains (host port 5499)
cp .env.example .env # set PGTT_GUI_SECRET; uncomment PGTT_GUI_ADMIN_* to seed a login
cd frontend && npm install && npm run build && cd .. # build + embed the UI
make run # loads .env, serves http://localhost:8080make run reads .env. To get a first login, uncomment PGTT_GUI_ADMIN_EMAIL / PGTT_GUI_ADMIN_PASSWORD in it (seeded on startup while no users exist), or create the first admin via POST /api/auth/setup.
For a live-reloading frontend during development: cd frontend && npm run dev (Vite on :5173, proxies the API to :8080).
Useful targets: make check (gofmt + vet + unit tests) · make itest (integration tests against the harness) · make docker-build (production image) · make up / make down (full demo stack).
| Backend | Go (stdlib net/http with Go 1.22+ routing), pgx/v5 + pool, inline SQL, no ORM. The UI is embedded via go:embed → one static, shell-less binary. |
| Frontend | React + TypeScript, Vite, TanStack Query; bespoke SVG charts; CSS variables for theming; i18n (EN / ES / DE / HI). |
| State store | A timetable_gui control schema inside one chosen PostgreSQL: installation registry (encrypted DSNs), users, sessions, per-installation grants, audit, saved searches. |
| Auth | Local users + RBAC (Viewer / Operator / Admin) with per-installation grants; server-side sessions; pluggable auth provider. |
| Scope | Schedule & chain management via SQL against each installation's timetable schema; worker health via pg_timetable's REST API. Workers are deployed and run externally. |
| Packaging | Single static binary with embedded UI · multi-stage Dockerfile (distroless, non-root) · docker-compose.yml demo stack · image published to GHCR. |
Design notes for contributors live in CONCEPT.md (architecture, data model, security) and DEVELOPMENT.md (engineering plan & status).
- Target database credentials are encrypted at rest with AES-256-GCM (key derived from
PGTT_GUI_SECRET); they are never returned to the browser. - All write/operate actions are RBAC-gated and audited (who, what, when, from where).
- Run behind TLS in production and set
AUTH_COOKIE_SECURE=true(enables theSecurecookie flag + HSTS). - The AI assistant is opt-in; when enabled it sends the relevant execution row (command, output, return code) to the configured gateway — point it at infrastructure you trust.
pg_timetable is an advanced, database-driven job scheduler for PostgreSQL by CYBERTEC. Studio manages it but does not replace it — you still deploy workers as usual.
- 📖 Documentation: https://cybertec-postgresql.github.io/pg_timetable/
- 🚀 Getting started / chains & scheduling: https://cybertec-postgresql.github.io/pg_timetable/latest/basic_jobs/
- 🧩 Built-in tasks: https://cybertec-postgresql.github.io/pg_timetable/latest/components/
- 💻 Source: https://github.com/cybertec-postgresql/pg_timetable
Issues and pull requests are welcome. Please run make check (and make itest against make dev-up) and cd frontend && npm run typecheck && npm run build before opening a PR.
PostgreSQL License — pure open source, matching pg_timetable's own license. © CYBERTEC PostgreSQL International GmbH.