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.
pscale sql <database> <branch> --org <org> --query "<SQL>" <FLAG>
--org is required.
Available flags
| Flag | Description |
|---|
--query <SQL> | SQL query to execute (required) |
--org <org> | Organization name (required) |
--role <role> | Access level: reader (default), writer, readwriter, admin |
--replica | Route reads to replicas |
--dbname <name> | PostgreSQL database name (default postgres) |
--keyspace <name> | MySQL/Vitess keyspace (default @primary, same as pscale shell) |
--force | Allow destructive SQL after explicit user approval (see below) |
-h, --help | Help for sql |
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
| Flag | Description |
|---|
-f, --format json | JSON on stdout (recommended for agents) |
--api-token, --service-token-id, --service-token | Authentication |
--api-url <URL> | API base URL |
--config <FILE> | Config file |
--debug | Debug mode |
--no-color | Disable color output |
Examples
Read query (default reader role):
pscale sql <database> <branch> --org <org> --format json --query "SELECT 1"
pscale sql <database> <branch> --org <org> --format json --replica --query "SELECT COUNT(*) FROM users"
pscale sql <database> <branch> --org <org> --format json --dbname postgres --query "SELECT version()"
pscale sql <database> <branch> --org <org> --format json --keyspace <keyspace> --query "SELECT 1"
pscale sql <database> <branch> --org <org> --format json --force --query "DELETE FROM staging_rows WHERE id = 1"
Need help?
Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.
