> connect & shell
Getting a real connection to a branch: an interactive SQL shell for quick queries, a secure local tunnel so your app can talk to PlanetScale without credentials in env files, and connection introspection for the day a runaway query pins your database. If you're wiring a Cloudflare Worker instead of a local process, skip the tunnel — use Hyperdrive or the serverless driver and keep these commands for debugging.
// connect & shell
9 commands$ pscale shell mydb main$ pscale shell mydb main --role reader$ pscale connect mydb add-users-table$ pscale connect mydb add-users-table --port 3309$ pscale connect mydb dev-branch --execute 'pnpm dev'$ pscale branch connections top mydb main$ pscale branch connections show mydb main --format json$ pscale branch connections kill mydb main <query-id> --query$ pscale branch connections kill-transaction mydb main <transaction-id>// faq
What's the difference between `pscale shell` and `pscale connect`?
`shell` opens an interactive SQL prompt — mysql for Vitess databases, psql for Postgres — through a secure proxy, no credentials needed. `connect` (Vitess-only) opens a persistent local tunnel on 127.0.0.1:3306 so any local client or app can connect as if the database were local. Use shell for queries, connect for running your app against a branch.
How does my deployed app connect — surely not through the tunnel?
Right: `connect` is a local-dev tool. In production you connect directly with credentials — a branch password (Vitess) or role (Postgres) in a standard connection string. On Cloudflare Workers, put that connection string in a Hyperdrive config (wrangler hyperdrive create) so the Worker gets pooling and query caching at the edge, or use the @planetscale/database fetch-based driver for Vitess.
A bad query is pinning my database — what do I do?
Run `pscale branch connections top` to watch live activity, find the offending query_id or connection_id with `connections show --format json`, then `connections kill` it. On Postgres branches you can also kill a single transaction with kill-transaction instead of dropping the whole connection.