Getting Started
Make sure to first set up your PlanetScale developer environment. Once you’ve installed thepscale 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.--org is required.
Available flags
Unlike
pscale shell, the default --role is reader. Pass --role admin (or writer / readwriter) for writes.
Destructive SQL
Queries containingDELETE, 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, postgresql, or neki), role, row_count, columns, rows, and next_steps; rows_affected when applicable and replica when --replica was used. Neki databases use the PostgreSQL query path.
Errors: one JSON object on stdout with status: "error", error, issues, and next_steps.
Destructive guard: status: "action_required", query_kind: "destructive", message, issues, and next_steps (includes a --force retry command).
Global flags
Examples
Read query (default reader role):pscale sql --replica appends the Postgres |replica username suffix. That is not how Neki routes replica traffic. For Neki replica reads, use pscale shell --replica. Do not add |replica to a Neki username.
Postgres or Neki with an explicit database name: