> ## 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

Vitess, Neki, and Postgres

## Getting Started

Make sure to first [set up your PlanetScale developer environment](/docs/cli/planetscale-environment-setup.md). 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.

> [!NOTE]
>
> **Requires `pscale` 0.292.0 or later.**

**Usage:**

```bash theme={null}
pscale sql <database> <branch> --org <org> --query "<SQL>" <FLAG>
```

Place **positional arguments first**, then flags. **`--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 a replica for PlanetScale Postgres or Vitess. For Neki, use [`pscale shell --replica`](/docs/cli/shell) instead, which sets `__neki.target=REPLICA`. |
| `--dbname <name>` | Postgres or Neki 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) |
| `--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 <URL>` | API base URL |
| `--config <FILE>` | Config file |
| `--debug` | Debug mode |
| `--no-color` | Disable color output |

## Examples

**Read query (default reader role):**

```bash theme={null}
pscale sql <database> <branch> --org <org> --format json --query "SELECT 1"
```

**Read from a PlanetScale Postgres or Vitess replica:**

```bash theme={null}
pscale sql <database> <branch> --org <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 <database> <branch> --org <org> --format json --dbname postgres --query "SELECT version()"
```

**MySQL multi-keyspace:**

```bash theme={null}
pscale sql <database> <branch> --org <org> --format json --keyspace <keyspace> --query "SELECT 1"
```

**Vertical output for wide rows:**

```bash theme={null}
pscale sql <database> <branch> --org <org> --replica --query "SHOW REPLICA STATUS\G"
```

**Destructive SQL (after user approval):**

```bash theme={null}
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](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.