> ## Documentation Index > Fetch the complete documentation index at: https://planetscale.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # PlanetScale CLI commands: sql export const PlatformAvailability = ({current, vitess, postgres, neki}) => { const docsHref = path => { if (!path) return path; const normalized = path.startsWith('/') ? path : `/${path}`; return normalized; }; const labels = { vitess: 'Vitess', postgres: 'Postgres', neki: 'Neki' }; const combinedLabels = { both: 'Vitess and Postgres', all: 'Vitess, Neki, and Postgres', 'postgres-neki': 'Postgres and Neki' }; if (combinedLabels[current]) { return

{combinedLabels[current]}

; } const hasVitess = current === 'vitess' || Boolean(vitess); const hasPostgres = current === 'postgres' || Boolean(postgres); const hasNeki = current === 'neki' || Boolean(neki); const only = [hasVitess, hasPostgres, hasNeki].filter(Boolean).length === 1; const engines = []; if (current === 'vitess' || current === 'postgres' || current === 'neki') engines.push(current); if (hasVitess && current !== 'vitess') engines.push('vitess'); if (hasNeki && current !== 'neki') engines.push('neki'); if (hasPostgres && current !== 'postgres') engines.push('postgres'); return

{engines.map(engine => { const isCurrent = current === engine; const href = docsHref(engine === 'vitess' ? vitess : engine === 'postgres' ? postgres : neki); const label = only ? `${labels[engine]} only` : labels[engine]; const state = isCurrent || !href ? 'current' : 'link'; if (isCurrent || !href) { return {label} ; } return {label} ; })}

; }; ## Getting Started Make sure to first [set up your PlanetScale developer environment](/docs/cli/planetscale-environment-setup). 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`](/docs/cli/shell) instead. **Requires `pscale` 0.292.0 or later.** **Usage:** ```bash theme={null} pscale sql --org --query "" ``` Place **positional arguments first**, then flags. **`--org` is required.** ### Available flags | **Flag** | **Description** | | - | - | | `--query ` | SQL query to execute **(required)** | | `--org ` | Organization name **(required)** | | `--role ` | Access level: `reader` (default), `writer`, `readwriter`, `admin` | | `--replica` | Route reads to a replica for PlanetScale Postgres or Vitess. For Neki, use [`pscale shell --replica`](/docs/cli/shell) instead, which sets `__neki.target=REPLICA`. | | `--dbname ` | Postgres or Neki database name (default `postgres`) | | `--keyspace ` | MySQL/Vitess keyspace (default `@primary`, same as `pscale shell`) | | `--force` | Allow destructive SQL after explicit user approval (see below) | | `--vertical` | Print each row vertically, one column per line. Ending a query with `\G` has the same effect. | | `-h`, `--help` | Help for `sql` | Unlike [`pscale shell`](/docs/cli/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`, `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 | **Flag** | **Description** | | - | - | | `-f`, `--format json` | JSON on stdout (recommended for agents) | | `--api-token`, `--service-token-id`, `--service-token` | Authentication | | `--api-url ` | API base URL | | `--config ` | Config file | | `--debug` | Debug mode | | `--no-color` | Disable color output | ## Examples **Read query (default reader role):** ```bash theme={null} pscale sql --org --format json --query "SELECT 1" ``` **Read from a PlanetScale Postgres or Vitess replica:** ```bash theme={null} pscale sql --org --format json --replica --query "SELECT COUNT(*) FROM users" ``` `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`](/docs/cli/shell). Do not add `|replica` to a Neki username. **Postgres or Neki with an explicit database name:** ```bash theme={null} pscale sql --org --format json --dbname postgres --query "SELECT version()" ``` **MySQL multi-keyspace:** ```bash theme={null} pscale sql --org --format json --keyspace --query "SELECT 1" ``` **Vertical output for wide rows:** ```bash theme={null} pscale sql --org --replica --query "SHOW REPLICA STATUS\G" ``` **Destructive SQL (after user approval):** ```bash theme={null} pscale sql --org --format json --force --query "DELETE FROM staging_rows WHERE id = 1" ``` ## Need help? Get help from [the PlanetScale Support team](https://planetscale.com/contact?initial=support), or join our [Discord community](https://pscale.link/community) to see how others are using PlanetScale. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.