Inspect live Neki connections

Overview

Connections shows the client sessions currently open on a Neki branch’s routers. If a session is stuck, you can cancel its query or terminate the session.

Connections only shows router sessions, not the connections between routers and each shard’s Postgres instances.

PlanetScale’s own administrative sessions and non-client backends aren’t shown.

View connections in the dashboard

Select a database and branch, then select Connections. The list refreshes automatically and shows one row per router session:

Column	Meaning
PID	The session’s process ID on its router. PIDs are unique per router, not per branch.
Router group	The router group the session is connected to.
Availability zone	The zone of the router serving the session.
State	The session state, for example `active`, `idle`, or `idle in transaction`.
Duration	Time since the session’s transaction started, or its query if it has no open transaction, or the session itself if neither.
User	The database role the client connected as.
Application	The client’s `application_name`.
Query	The session’s current query, or its most recent one if it’s idle.

Select a row to see the session’s details, including the shard backends serving it.

View connections in the CLI

show prints the current sessions once, and top opens a live terminal view:

pscale branch connections show <database> <branch>
pscale branch connections top <database> <branch>

show prints each session with its IDs and shard backends. Add --format json for scripts and AI agents. In top, press s to switch the sort between transaction start and duration, and enter to open a session’s details.

Capture and replay

Record a top session to a trace file and replay it later:

# record while you watch
pscale branch connections top <database> <branch> --capture trace.jsonl

# record without the interactive view
pscale branch connections top <database> <branch> --capture trace.jsonl --duration 30m

# replay the trace
pscale branch connections top --replay trace.jsonl

In the live view, press C to start or stop a capture. The capture includes the last few minutes of history that top already has in memory. If you didn’t pass --capture, the trace is written to connections-<timestamp>.jsonl in the current directory.

Cancel a query or terminate a session

Action	Dashboard / `top`	CLI command	What happens
Cancel query	Cancel query / `c`	`kill <database> <branch> <query_id> --query`	The router cancels the statement the session is running. The connection stays open, and the client receives a canceled-query error (SQLSTATE `57014`). If the session was in a transaction, the transaction is aborted and the client must roll back before running more statements, as in Postgres.
Kill transaction	Terminate transaction / `k`	`kill-transaction <database> <branch> <transaction_id>`	Terminates the session, but only if it still has the open transaction you saw.
Force terminate	Terminate connection / `K`	`kill <database> <branch> <connection_id>`	The router cancels anything the session is running, then closes the client’s connection. Any open transaction is rolled back, the same as if the client had disconnected.

Before acting, PlanetScale checks that the session is still the one you saw. If the query finished, the transaction ended, or the PID now belongs to a new session, the action is rejected. In the CLI, the action commands take effect immediately with no confirmation prompt. Scripts and AI agents should get IDs from show --format json, act on one session at a time, and run show again to confirm the result. An agent should get a person’s approval before running an action.

Permissions

Connections is available to signed-in users (for the CLI, authenticate with pscale auth login) but not when using service tokens. What you can do depends on your role and whether the branch is a production branch. Acting means cancelling a query or terminating a session.

Role	View dev	Act dev	View production	Act production
Organization Member	✓	✓
Organization Analyst	✓	✓	✓
Organization Administrator	✓	✓	✓	✓
Database Administrator (for that database)	✓	✓	✓	✓

Database Administrator access can be granted directly or through a team. If you don’t have the required role, the request fails with a permission error. See Access control for the full role model.

connections CLI reference

Monitoring overview

Query Insights

Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.

Architecture

Pricing

Platform

Guides

Inspect live Neki connections

Overview

View connections in the dashboard

View connections in the CLI

Capture and replay

Cancel a query or terminate a session

Permissions

connections CLI reference

Monitoring overview

Query Insights

Need help?

​Overview

​View connections in the dashboard

​View connections in the CLI

​Capture and replay

​Cancel a query or terminate a session

​Permissions

​Related documentation

connections CLI reference

Monitoring overview

Query Insights

​Need help?

Overview

View connections in the dashboard

View connections in the CLI

Capture and replay

Cancel a query or terminate a session

Permissions

Related documentation

Need help?