Skip to main content

​
Getting Started

Make sure to first set up your PlanetScale developer environment. Once you’ve installed the pscale CLI, you can interact with PlanetScale and manage your databases straight from the command line.

​
The sql command

Execute a single SQL query against a database branch without an interactive shell. Intended for agents and scripts. For interactive sessions, use pscale shell instead.
Requires pscale 0.292.0 or later.
Usage:
Place positional arguments first, then flags. --org is required.

​
Available flags

Unlike pscale shell, the default --role is reader. Pass --role admin (or writer / readwriter) for writes.

​
Destructive SQL

Queries containing DELETE, DROP, or TRUNCATE as statement keywords are blocked unless --force is passed. With --format json, blocked queries return "status": "action_required" and "query_kind": "destructive". Agents must ask the user to approve, then re-run with --force. Never use --force without explicit user approval.

​
JSON output

Use --format json for automation. Success: status, database, branch, kind (mysql or postgresql), role, row_count, columns, rows; replica when --replica was used. Errors: one JSON object on stdout with status: "error", error, and next_steps. Destructive guard: status: "action_required", query_kind: "destructive", issues, and next_steps (includes a --force retry command).

​
Global flags

​
Examples

Read query (default reader role):
Read from replica:
PostgreSQL with explicit database name:
MySQL multi-keyspace:
Destructive SQL (after user approval):

​
Need help?

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