The pscale branch connections command shows what is running on a Vitess database branch right now: the
active sessions on a primary tablet, what each is executing, and how long it has been running. If a
session is stuck, you can cancel its query or terminate the connection directly.It is the live equivalent of running SHOW FULL PROCESSLIST and KILL against a primary, without
opening a MySQL shell or holding database credentials. The command detects the branch engine
automatically; this guide covers Vitess branches. For Postgres, see
Inspect live Postgres connections.There are two ways to use it:
Interactively, with pscale branch connections top — a terminal UI for watching activity live and
taking action from the keyboard.
From scripts or AI agents, with pscale branch connections show plus the kill command —
one-shot, structured output designed to be safe to automate.
For Vitess, connections targets one keyspace and one shard. If a branch has more than one keyspace, or a keyspace is
sharded, pass --keyspace and --shard to choose the tablet. An interactive top prompts you to
pick when a target is missing.
Run top in an interactive terminal to launch the live view:
pscale branch connections top <database> <branch>
Target a specific keyspace and shard:
pscale branch connections top <database> <branch> --keyspace <keyspace> --shard <shard>
The view refreshes about once per second; press space to pause. You can scrub back through the
recent in-memory history without leaving the live view: [ and ] step one sample at a time, { and
} jump to the oldest or newest, and } returns to live-follow.
Press enter on a row to open the detail view. It shows the session’s full metadata — pid,
tablet, state, duration, user, database, client_addr, connection_id, and query_id —
followed by the complete statement text, scrollable and never truncated. Press esc to go back, and
? at any time for the in-app key reference.
You can record a session to a trace file and review it later:
# record while you watchpscale branch connections top <database> <branch> --capture trace.jsonl# or record headlessly, e.g. during an incidentpscale branch connections top <database> <branch> --capture trace.jsonl --duration 30m# replay the trace in the same UIpscale branch connections top --replay trace.jsonl
In the live view, press C to start or stop capturing on the fly. The same [ ] { } history keys work
in replay to move through the recording.
For a Vitess branch, the envelope reports "database_kind": "mysql" and a topology object with the
keyspace, shard, and tablet the rows came from. Each connection carries tablet-qualified
connection_id and query_id values (for example zone1-1001-101). Pass those to the action
commands:
The action sub-commands take effect immediately and have no confirmation prompt — the confirmation only exists in
the interactive TUI. Always target a session by the query_id or connection_id from a recent show.
Access to Connections is tied to your user account and your role on the database, and what you can do
depends on whether the branch is a production branch. It is
available to signed-in users (for the CLI, authenticate with pscale auth login), not to service
tokens.There are two levels of access:
View — see the connection list and the top view.
Act — cancel a query or terminate a connection.
Production branches are gated more tightly than development branches:
Role
View dev
Act dev
View production
Act production
Organization Member
✓
✓
Organization Analyst
✓
✓
✓
Organization Administrator
✓
✓
✓
✓
Database Administrator (for that database)
✓
✓
✓
✓
In short: any organization member can view and act on development branches; viewing a production branch requires Analyst or higher; acting on a production branch requires Administrator. Database Administrator access can be granted directly or through a team — everyone on a team that includes the database has Database Administrator access to it.If you do not have the required role, the command returns a permission error (HTTP 403) for the action you attempted. See Access control for the full role and team model.
connections polls about once per second. Each refresh runs SHOW FULL PROCESSLIST on the primary
tablet, so on a very busy primary you can raise --interval to poll less often. The captured_at
timestamp, and the freshness indicator in the TUI header, always tell you how old the current snapshot
is.
