queryview 0.0.7__tar.gz → 0.0.8__tar.gz

{queryview-0.0.7 → queryview-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: queryview
-Version: 0.0.7
+Version: 0.0.8
 Summary: Local SQL workbench for ClickHouse, Postgres and DuckDB, with a built-in MCP server for AI agents
 Project-URL: Homepage, https://github.com/kolodkin/queryview
 Project-URL: Repository, https://github.com/kolodkin/queryview
@@ -127,6 +127,17 @@ To let Docker own the location instead, swap the path for a named volume,
 ownership is already right and there is nothing to create up front, but the
 state no longer lines up with a local run.
 
+### Connecting to databases on your machine
+
+Inside the container, `localhost` is the container itself. To reach a database:
+
+- **On the host:** use `host.docker.internal` (on Linux, add
+  `--add-host=host.docker.internal:host-gateway`).
+- **In another container:** `docker network connect <net> queryview`, then use
+  its container name as the host.
+- **Host networking:** `--network host` makes `localhost` your machine (Linux,
+  or Docker Desktop 4.34+ with host networking enabled); `-p` is then ignored.
+
 ### Git sync
 
 The image ships `git`, so workspace git sync works in the container, and its
@@ -179,10 +190,11 @@ connection and rewrite workspace git state, so don't publish the port. Bind the
 container to loopback — `docker run -p 127.0.0.1:8000:8000 ...` — since a plain
 `-p 8000:8000` listens on all interfaces.
 
-Tools: `run_query` (read-only SQL, rows returned to the agent), `push_query`
-and `push_dashboard` (fill a live browser session), `list_queries` /
-`list_dashboards`, and `git_store` / `git_history` / `git_restore` (workspace
-git backups). The push tools target an **armed** browser session: enable
+Tools: `list_connections` (saved connection names; call it before `run_query`
+when unsure), `run_query` (read-only SQL, rows returned to the agent),
+`push_query` and `push_dashboard` (fill a live browser session),
+`list_queries` / `list_dashboards`, and `git_store` / `git_history` /
+`git_restore` (workspace git backups). The push tools target an **armed** browser session: enable
 "Allow remote control" from the agent icon next to the connection pill and use
 the session id it shows. See [docs/remote.md](docs/remote.md) for the full
 protocol.
@@ -198,7 +210,9 @@ and let [git sync](docs/gitsync.md) do it.
 ## Documentation
 
 - [queryview.md](docs/queryview.md) — the single-prompt page.
-- [connect.md](docs/connect.md) — connections, drivers, sessions, storage.
+- [connect.md](docs/connect.md) — connections, drivers, storage.
+- [session.md](docs/session.md) — sessions: what a tab remembers, refresh and
+  new-tab behaviour, the session switcher.
 - [query.md](docs/query.md) — the query panel: pagination, predefined queries, CSV.
 - [explorer.md](docs/explorer.md) — the table navigator.
 - [dashboard.md](docs/dashboard.md) — dashboards and how agents author them.

{queryview-0.0.7 → queryview-0.0.8}/README.md

@@ -103,6 +103,17 @@ To let Docker own the location instead, swap the path for a named volume,
 ownership is already right and there is nothing to create up front, but the
 state no longer lines up with a local run.
 
+### Connecting to databases on your machine
+
+Inside the container, `localhost` is the container itself. To reach a database:
+
+- **On the host:** use `host.docker.internal` (on Linux, add
+  `--add-host=host.docker.internal:host-gateway`).
+- **In another container:** `docker network connect <net> queryview`, then use
+  its container name as the host.
+- **Host networking:** `--network host` makes `localhost` your machine (Linux,
+  or Docker Desktop 4.34+ with host networking enabled); `-p` is then ignored.
+
 ### Git sync
 
 The image ships `git`, so workspace git sync works in the container, and its
@@ -155,10 +166,11 @@ connection and rewrite workspace git state, so don't publish the port. Bind the
 container to loopback — `docker run -p 127.0.0.1:8000:8000 ...` — since a plain
 `-p 8000:8000` listens on all interfaces.
 
-Tools: `run_query` (read-only SQL, rows returned to the agent), `push_query`
-and `push_dashboard` (fill a live browser session), `list_queries` /
-`list_dashboards`, and `git_store` / `git_history` / `git_restore` (workspace
-git backups). The push tools target an **armed** browser session: enable
+Tools: `list_connections` (saved connection names; call it before `run_query`
+when unsure), `run_query` (read-only SQL, rows returned to the agent),
+`push_query` and `push_dashboard` (fill a live browser session),
+`list_queries` / `list_dashboards`, and `git_store` / `git_history` /
+`git_restore` (workspace git backups). The push tools target an **armed** browser session: enable
 "Allow remote control" from the agent icon next to the connection pill and use
 the session id it shows. See [docs/remote.md](docs/remote.md) for the full
 protocol.
@@ -174,7 +186,9 @@ and let [git sync](docs/gitsync.md) do it.
 ## Documentation
 
 - [queryview.md](docs/queryview.md) — the single-prompt page.
-- [connect.md](docs/connect.md) — connections, drivers, sessions, storage.
+- [connect.md](docs/connect.md) — connections, drivers, storage.
+- [session.md](docs/session.md) — sessions: what a tab remembers, refresh and
+  new-tab behaviour, the session switcher.
 - [query.md](docs/query.md) — the query panel: pagination, predefined queries, CSV.
 - [explorer.md](docs/explorer.md) — the table navigator.
 - [dashboard.md](docs/dashboard.md) — dashboards and how agents author them.

{queryview-0.0.7 → queryview-0.0.8}/backend/queryview/connect.py

@@ -192,13 +192,6 @@ def _row_to_stored(row: Connection | None) -> StoredConnection | None:
     )
 
 
-async def _latest_active_connection() -> StoredConnection | None:
-    await _ensure_schema()
-    async with AsyncSession(_engine_for_db()) as s:
-        row = (await s.exec(select(Connection).order_by(col(Connection.last_active_at).desc()).limit(1))).first()
-        return _row_to_stored(row)
-
-
 async def list_connection_names() -> list[str]:
     """All saved connection names, most-recently-active first (for `connect`
     autocomplete)."""
@@ -208,6 +201,27 @@ async def list_connection_names() -> list[str]:
         return list(rows.all())
 
 
+async def list_connections() -> list[dict[str, Any]]:
+    """Every saved connection as {name, type, database}, most-recently-active
+    first. Reads only those columns: the encrypted config (host, credentials)
+    never leaves this module."""
+    await _ensure_schema()
+    async with AsyncSession(_engine_for_db()) as s:
+        rows = await s.exec(
+            select(Connection.name, Connection.type, Connection.database).order_by(
+                col(Connection.last_active_at).desc()
+            )
+        )
+        return [{"name": n, "type": t, "database": d} for n, t, d in rows.all()]
+
+
+async def unknown_connection_message(name: str) -> str:
+    """The error for an unresolvable connection name, listing the valid ones so
+    a caller (typically an agent) can retry without guessing."""
+    names = await list_connection_names()
+    return f'no connection named "{name}"; available: {", ".join(names) if names else "(none)"}'
+
+
 async def _connection_by_name(name: str) -> StoredConnection | None:
     await _ensure_schema()
     async with AsyncSession(_engine_for_db()) as s:
@@ -248,18 +262,6 @@ _sessions: OrderedDict[str, _SessionState] = OrderedDict()
 MAX_SESSIONS = int(os.environ.get("MAX_SESSIONS", "1000"))
 
 
-# Cookies that explicitly disconnected. Kept distinct from "never seen" so
-# _ensure_session can suppress auto-reconnect for them; bounded like _sessions.
-_disconnected: OrderedDict[str, None] = OrderedDict()
-
-
-def _mark_disconnected(sid: str) -> None:
-    _disconnected[sid] = None
-    _disconnected.move_to_end(sid)
-    while len(_disconnected) > MAX_SESSIONS:
-        _disconnected.popitem(last=False)
-
-
 def _get_session_entry(sid: str) -> _SessionState | None:
     s = _sessions.get(sid)
     if s is not None:
@@ -274,13 +276,32 @@ def _set_session_entry(sid: str, state: _SessionState) -> None:
         _sessions.popitem(last=False)
 
 
+_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
+
+
+def _in_container() -> bool:
+    return Path("/.dockerenv").exists()
+
+
+def _with_localhost_hint(message: str, config: DriverConfig) -> str:
+    """Inside a container `localhost` is the container itself, so a failed
+    connect to it most likely meant the host machine's database."""
+    host = getattr(config, "host", None)
+    if host in _LOCAL_HOSTS and _in_container():
+        return (
+            f"{message} — QueryView runs in a container, where {host} is the container "
+            "itself; for a database on your machine use host.docker.internal"
+        )
+    return message
+
+
 async def _build_session(
     name: str, config: DriverConfig, database: str | None, conn_type: str = "clickhouse"
 ) -> tuple[_SessionState | None, str | None]:
     """List a connection's databases and build a session object."""
     ok, result = await DRIVERS[conn_type].list_databases(config)
     if not ok:
-        return None, result  # type: ignore[return-value]
+        return None, _with_localhost_hint(result, config)  # type: ignore[arg-type]
     databases: list[str] = result  # type: ignore[assignment]
     return (
         _SessionState(
@@ -295,22 +316,26 @@ async def _build_session(
 
 
 async def _ensure_session(sid: str) -> None:
-    """At session start (a cookie we haven't seen), reconnect the latest active
-    connection so a fresh session resumes where the last one left off."""
-    if _get_session_entry(sid):
+    """Rebuild this session's live driver state from its row. The row is the
+    durable truth; `_sessions` is only a cache of the decrypted config and the
+    database list, so a backend restart costs one reconnect, not the session."""
+    if not sid or _get_session_entry(sid):
         return
-    if sid in _disconnected:
+    rec = await sessions.get_session_rec(sid)
+    if rec is None or rec.connection_name is None:
         return
-    stored = await _latest_active_connection()
+    stored = await _connection_by_name(rec.connection_name)
     if stored is None:
+        # The connection was deleted, or its config no longer decrypts. The
+        # session stays as it is and reads as disconnected; the user reconnects.
         return
-    state, _ = await _build_session(stored.name, stored.config, stored.database, stored.type)
+    state, _ = await _build_session(stored.name, stored.config, rec.database, stored.type)
     if state is not None:
         _set_session_entry(sid, state)
 
 
 async def get_session(sid: str) -> dict[str, Any]:
-    """This session's state; auto-connects the latest active for an unseen cookie."""
+    """This session's connection state, rebuilt from its row if not cached."""
     await _ensure_session(sid)
     s = _get_session_entry(sid)
     if s is None:
@@ -329,9 +354,9 @@ async def connect_new(sid: str, name: str, config: DriverConfig, conn_type: str)
     state, message = await _build_session(name, config, None, conn_type)
     if state is None:
         return {"ok": False, "message": message}
-    _disconnected.pop(sid, None)
     _set_session_entry(sid, state)
     await _save_active_connection(name, config, conn_type)
+    await sessions.set_connection(sid, name)
     return {"ok": True, "name": name, "type": state.type, "databases": state.databases}
 
 
@@ -341,25 +366,24 @@ async def open_saved(sid: str, name: str) -> dict[str, Any]:
     if stored is None:
         return {
             "ok": False,
-            "message": f'no connection named "{name}"',
+            "message": await unknown_connection_message(name),
             "not_found": True,
         }
     # Reset the database so `connect <name>` always lands on the picker.
     state, message = await _build_session(stored.name, stored.config, None, stored.type)
     if state is None:
         return {"ok": False, "message": message}
-    _disconnected.pop(sid, None)
     _set_session_entry(sid, state)
     await _touch_connection(name)
+    await sessions.set_connection(sid, name)
     return {"ok": True, "name": name, "type": state.type, "databases": state.databases}
 
 
 async def disconnect(sid: str) -> dict[str, Any]:
-    """Drop this session's active connection and suppress auto-reconnect until
-    it connects again. Saved connections are left intact — `connect <name>`
-    still reopens them."""
+    """Drop this session's active connection. Saved connections are left intact
+    — `connect <name>` still reopens them."""
     _sessions.pop(sid, None)
-    _mark_disconnected(sid)
+    await sessions.set_connection(sid, None)
     return {"ok": True}
 
 
@@ -372,6 +396,7 @@ async def select_database(sid: str, database: str) -> dict[str, Any]:
         return {"ok": False, "message": "unknown database", "reason": "unknown"}
     s.database = database
     await _save_selected_database(s.name, database)
+    await sessions.set_database(sid, database)
     return {"ok": True}
 
 
@@ -452,3 +477,9 @@ async def export_csv(
     if not r.ok:
         return {"ok": False, "message": r.value}
     return {"ok": True, "output": r.value}
+
+
+# Imported last, not at the top: sessions.py builds on this module's engine and
+# schema helpers, so a top-level import here would be a cycle. connect.py calls
+# into it only to write a session's connection through.
+from . import sessions  # noqa: E402

{queryview-0.0.7 → queryview-0.0.8}/backend/queryview/dashboard_queries.py

@@ -7,7 +7,7 @@ from __future__ import annotations
 
 from typing import Any
 
-from .connect import _connection_by_name
+from .connect import _connection_by_name, unknown_connection_message
 from .drivers import DRIVERS
 from .drivers.base import rows_to_columns
 
@@ -33,7 +33,7 @@ async def run_queries_for_connection(
         return {
             "ok": False,
             "reason": "no-connection",
-            "message": f'no connection named "{name}"',
+            "message": await unknown_connection_message(name),
         }
     driver = DRIVERS[stored.type]
     if driver.requires_database and not stored.database:

{queryview-0.0.7 → queryview-0.0.8}/backend/queryview/main.py

@@ -1,10 +1,10 @@
-"""FastAPI app: the JSON API under /api/*, the per-session cookie, and (when
-SERVE_STATIC=1) serving the built SPA with an index.html fallback."""
+"""FastAPI app: the JSON API under /api/*, the X-QV-Session header that names
+the caller's session, and (when SERVE_STATIC=1) serving the built SPA with an
+index.html fallback."""
 
 from __future__ import annotations
 
 import os
-import uuid
 from contextlib import asynccontextmanager
 from functools import lru_cache
 from pathlib import Path
@@ -19,7 +19,7 @@ from fastapi.responses import (
     StreamingResponse,
 )
 
-from . import gitsync, remote, workspaces, yamlio
+from . import gitsync, remote, sessions, workspaces, yamlio
 from .connect import (
     _ensure_schema,
     connect_new,
@@ -116,16 +116,11 @@ async def mcp_slash_redirect() -> RedirectResponse:
 
 
 @app.middleware("http")
-async def session_cookie(request: Request, call_next):
-    sid = request.cookies.get("qv_session")
-    new_session = sid is None
-    if not sid:
-        sid = str(uuid.uuid4())
-    request.state.sid = sid
-    response = await call_next(request)
-    if new_session:
-        response.set_cookie("qv_session", sid, path="/", httponly=True, samesite="lax")
-    return response
+async def session_header(request: Request, call_next):
+    """Identify the session from the header the SPA sends on every /api call.
+    There is no cookie: a session is named by its id, not by the browser."""
+    request.state.sid = request.headers.get("X-QV-Session") or ""
+    return await call_next(request)
 
 
 @app.get("/api/health")
@@ -138,6 +133,118 @@ async def session(request: Request) -> dict[str, Any]:
     return await get_session(request.state.sid)
 
 
+_SESSION_ERRORS = {
+    "unknown": (404, "unknown session"),
+    "held": (409, "session is open in another tab"),
+}
+
+
+def _session_error(reason: str) -> JSONResponse:
+    """A session store reason code as a response. The store returns codes, not
+    prose, so rewording a message cannot silently change an HTTP status."""
+    status, message = _SESSION_ERRORS.get(reason, (409, reason or "cannot do that"))
+    return JSONResponse({"ok": False, "message": message}, status_code=status)
+
+
+def _str_or_none(body: dict[str, Any], key: str) -> str | None:
+    """A string field of a patch body, or None when absent. Unlike `_clean_str`
+    an empty string is kept: that is how a label unpins."""
+    value = body.get(key)
+    return value if isinstance(value, str) else None
+
+
+def _session_payload(rec: sessions.SessionRec) -> dict[str, Any]:
+    return {
+        "id": rec.id,
+        "label": sessions.display_label(rec),
+        "pinned": rec.label is not None,
+        "connection": rec.connection_name,
+        "database": rec.database,
+        "workspace": rec.workspace,
+        "url": rec.url,
+        "ui": rec.ui,
+    }
+
+
+# Resolve and claim this tab's session (see sessions.attach); doubles as the
+# claim heartbeat.
+@app.post("/api/sessions/attach")
+async def sessions_attach(request: Request):
+    b = await _read_json(request) or {}
+    tab = _clean_str(b.get("tab"))
+    if not tab:
+        return JSONResponse({"ok": False, "message": "tab is required"}, status_code=400)
+    raw_id = _clean_str(b.get("session_id"))
+    rec, created = await sessions.attach(tab, raw_id or None)
+    return {"ok": True, "created": created, "session": _session_payload(rec)}
+
+
+# Switch this tab to a specific session, or (id omitted/null) to a new one.
+@app.post("/api/sessions/select")
+async def sessions_select(request: Request):
+    b = await _read_json(request) or {}
+    tab = _clean_str(b.get("tab"))
+    if not tab:
+        return JSONResponse({"ok": False, "message": "tab is required"}, status_code=400)
+    raw_id = _clean_str(b.get("id"))
+    rec, reason = await sessions.select_session(tab, raw_id or None)
+    if rec is None:
+        return _session_error(reason)
+    return {"ok": True, "session": _session_payload(rec)}
+
+
+@app.get("/api/sessions")
+async def sessions_list() -> dict[str, Any]:
+    return {"sessions": await sessions.list_sessions()}
+
+
+@app.patch("/api/sessions/{sid}")
+async def sessions_patch(sid: str, request: Request):
+    b = await _read_json(request) or {}
+    ui = b.get("ui")
+    rec = await sessions.patch_session(
+        sid,
+        url=_str_or_none(b, "url"),
+        ui=ui if isinstance(ui, dict) else None,
+        label=_str_or_none(b, "label"),
+        workspace=_str_or_none(b, "workspace"),
+    )
+    if rec is None:
+        return JSONResponse({"ok": False, "message": "unknown session"}, status_code=404)
+    return {"ok": True, "session": _session_payload(rec)}
+
+
+@app.delete("/api/sessions/{sid}")
+async def sessions_delete(sid: str):
+    ok, reason = await sessions.delete_session(sid)
+    if not ok:
+        return _session_error(reason)
+    return {"ok": True}
+
+
+# The pagehide beacon: apply whatever the tab had not flushed yet, then free its
+# claim rather than waiting out the TTL. A reload fires pagehide, so this is what
+# keeps a change made inside the client's debounce window.
+@app.post("/api/sessions/release")
+async def sessions_release(request: Request):
+    b = await _read_json(request) or {}
+    tab = _clean_str(b.get("tab"))
+    if not tab:
+        return {"ok": True}
+    sid = _clean_str(b.get("session_id"))
+    if sid:
+        ui = b.get("ui")
+        await sessions.patch_session(
+            sid,
+            url=_str_or_none(b, "url"),
+            ui=ui if isinstance(ui, dict) else None,
+            label=_str_or_none(b, "label"),
+            workspace=_str_or_none(b, "workspace"),
+        )
+    await sessions.release(tab)
+    return {"ok": True}
+
+
 # Drop this session's active connection (disconnect command).
 @app.post("/api/db/disconnect")
 async def db_disconnect(request: Request) -> dict[str, Any]:
@@ -375,7 +482,9 @@ async def _event_stream(remote_id: str, request: Request):
 # arms "remote control". Closing the EventSource unregisters the channel.
 @app.get("/api/remote/events")
 async def remote_events(request: Request):
-    remote_id = remote.register()
+    # EventSource cannot send headers, so the browser passes its session id in
+    # the query string; other callers still identify by header.
+    remote_id = remote.register(request.query_params.get("session") or request.state.sid)
     return StreamingResponse(
         _event_stream(remote_id, request),
         media_type="text/event-stream",
@@ -419,26 +528,6 @@ async def remote_push(request: Request):
     return {"ok": ok, "message": message}
 
 
-@app.post("/api/remote/db")
-async def remote_db(request: Request):
-    """Browser reports the database its live session targets, so the agent's
-    push_query/push_dashboard responses can echo it. Called on arm and whenever
-    the active database changes."""
-    body = await _read_json(request)
-    b = body if isinstance(body, dict) else {}
-    raw_sid = b.get("session_id")
-    session_id = raw_sid.strip() if isinstance(raw_sid, str) else ""
-    raw_db = b.get("database")
-    database = raw_db if isinstance(raw_db, str) and raw_db else None
-    if not session_id:
-        return JSONResponse({"ok": False, "message": "session_id required"}, status_code=400)
-    ok = remote.set_session_database(session_id, database)
-    if "workspace" in b:
-        raw_ws = b.get("workspace")
-        remote.set_session_workspace(session_id, raw_ws if isinstance(raw_ws, str) and raw_ws else None)
-    return {"ok": ok}
-
-
 @app.post("/api/remote/lock")
 async def remote_lock(request: Request):
     """Browser-only edit-lock control for a live session. action=acquire is sent

{queryview-0.0.7 → queryview-0.0.8}/backend/queryview/mcp_server.py

@@ -8,7 +8,7 @@ from typing import Any
 
 from mcp.server.fastmcp import FastMCP
 
-from . import gitsync, remote
+from . import gitsync, remote, sessions
 from .dashboards import _push_dashboard
 from .queries import list_predefined_queries_view
 
@@ -29,9 +29,11 @@ async def push_query(
 ) -> dict[str, Any]:
     """Push a SQL query to a live QueryView browser session.
 
-    The targeted browser fills its query panel and auto-runs the query. Get the
-    `session_id` from the QueryView UI: the agent icon next to the connection
-    status pill, after enabling "Allow remote control".
+    The targeted browser fills its query panel and auto-runs the query against
+    the session's own connection. Get the `session_id` from the QueryView UI:
+    the agent icon next to the connection status pill, after enabling "Allow
+    remote control". To explore data first with run_query, call
+    list_connections for the saved connection names rather than guessing one.
 
     Args:
         session_id: The session id shown in the QueryView popover.
@@ -61,7 +63,7 @@ async def push_query(
         "name": name,
     }
     ok, message = remote.push(session_id, payload)
-    return {"ok": ok, "message": message, "database": remote.session_database(session_id)}
+    return {"ok": ok, "message": message, "database": await sessions.database_of(session_id)}
 
 
 def _columns_to_rows(cols: dict[str, list]) -> dict[str, Any]:
@@ -92,6 +94,10 @@ async def run_query(
     `database` is the connection's currently-selected database (the user can
     change it from the connection pill), so check it before deciding whether to
     fully-qualify tables as db.table.
+
+    `connection` is a saved connection name. The default "clickhouse" is only a
+    guess: if you don't know the name, call list_connections first. An unknown
+    name fails with a message listing the available ones.
     """
     from .connect import _connection_by_name
     from .dashboard_queries import run_queries_for_connection
@@ -113,15 +119,41 @@ async def run_query(
 
 
 async def _session_workspace_rec(session_id: str | None):
-    """The workspace the given armed session is on (reported by the browser),
-    else the default workspace. MCP is deliberately workspace-unaware: the
-    human picks the workspace in the UI; the agent works in session scope."""
+    """The workspace the given session is on, read from its row, else the
+    default workspace. MCP is deliberately workspace-unaware: the human picks
+    the workspace in the UI; the agent works in session scope."""
     from . import workspaces
 
-    name = remote.session_workspace(session_id) if session_id else None
+    name = await sessions.workspace_of(session_id) if session_id else None
     return await workspaces.resolve(name or workspaces.DEFAULT_WORKSPACE)
 
 
+@mcp.tool()
+async def list_connections(session_id: str | None = None) -> dict[str, Any]:
+    """List the saved connections: the valid `connection` names for run_query
+    and push_dashboard. Call this before run_query / push_query whenever the
+    connection name is unknown — don't guess.
+
+    Returns {"connections": [{name, type, database}]}, most recently used
+    first; `database` is the connection's currently-selected database (null if
+    none). Hosts and credentials are never returned. With a `session_id`, also
+    returns "session_connection": the connection that session is on (null if
+    disconnected) — the natural choice for run_query.
+
+    Args:
+        session_id: Optional armed-session id. Connections are shared across
+            workspaces, so the list is the same for every session; the id only
+            adds "session_connection".
+    """
+    from .connect import list_connections as _list_connections
+
+    out: dict[str, Any] = {"connections": await _list_connections()}
+    if session_id:
+        rec = await sessions.get_session_rec(session_id)
+        out["session_connection"] = rec.connection_name if rec else None
+    return out
+
+
 @mcp.tool()
 async def list_queries(conn_type: str = "clickhouse", session_id: str | None = None) -> dict[str, Any]:
     """List the saved (predefined) queries for a connection type.
@@ -187,18 +219,25 @@ async def push_dashboard(
     Args:
         session_id: The session id shown in the QueryView popover.
         name: Dashboard name (the name the user's Save will persist under).
-        connection: Saved connection name the queries run against.
+        connection: Saved connection name the queries run against (see
+            list_connections).
         html: The dashboard HTML document (renders in a sandboxed iframe).
         queries: Map of query name to SQL.
 
-    Returns {ok, pushed, message}.
+    Returns {ok, pushed, message}. An unknown `connection` fails without
+    pushing, with a message listing the available names (see list_connections).
     """
+    from .connect import _connection_by_name, unknown_connection_message
+
+    if await _connection_by_name(connection) is None:
+        message = await unknown_connection_message(connection)
+        return {"ok": False, "pushed": False, "message": message, "database": None}
     pushed, message = await _push_dashboard(name, connection, html, queries, session_id or None)
     return {
         "ok": pushed,
         "pushed": pushed,
         "message": message,
-        "database": remote.session_database(session_id),
+        "database": await sessions.database_of(session_id),
     }