> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# PlanetScale

> Pull PlanetScale database and branch metrics into Squasher, and record deploy requests as deployments.

The PlanetScale connection lists your databases and branches, pulls branch metrics every 5 minutes,
and records deploy requests as deployments. Squasher uses a read-only organization service token. It
does not change anything in PlanetScale.

## Prerequisites

* A PlanetScale organization, and permission to create service tokens and webhooks in it.
* A Squasher API key with the `project:write` permission, if you connect with the CLI or the API.
  See [API keys](/api-reference/api-keys).

## Create a service token

1. In PlanetScale, open your organization settings and create a service token.
2. Give the token these organization permissions. All of them are read-only.

| Permission | What Squasher reads |
| - | - |
| `read_databases` | The databases in the organization |
| `read_branches` | The branches of each database |
| `read_metrics_endpoints` | The Prometheus metrics endpoints of each branch |
| `read_deploy_requests` | Deploy requests, so that deploy events have their data |

3. Copy the token ID and the token. PlanetScale shows the token one time.

## Connect PlanetScale

<Tabs>
  <Tab title="Dashboard">
    1. Open your project and select **Settings** in the sidebar, then the **Integrations** tab.
    2. On the **PlanetScale** card, select **Connect**.
    3. Enter the organization name, the token ID, and the token, then save.
  </Tab>

  <Tab title="CLI">
    The CLI reads the token from the `PLANETSCALE_SERVICE_TOKEN` environment variable or from stdin.
    It has no flag for the token, so the token does not stay in your shell history.

    ```bash theme={null}
    read -rs PLANETSCALE_SERVICE_TOKEN && export PLANETSCALE_SERVICE_TOKEN
    squasher integrations connect-planetscale \
      --project "$SQUASHER_PROJECT_ID" \
      --organization <organization> \
      --service-token-id <token-id>
    ```

    To read the token from stdin instead, add `--service-token-stdin` and pipe the token to the
    command.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST "https://api.squasher.ai/v1/projects/$SQUASHER_PROJECT_ID/provider-connections/planetscale" \
      -H "x-squasher-key: $SQUASHER_ADMIN_KEY" \
      -H "Content-Type: application/json" \
      -d "{\"organization\":\"<organization>\",\"service_token_id\":\"$PLANETSCALE_SERVICE_TOKEN_ID\",\"service_token\":\"$PLANETSCALE_SERVICE_TOKEN\"}"
    ```
  </Tab>
</Tabs>

Squasher checks the token before it saves the connection. The response gives the number of
databases that the token can read and the `webhook_url` for the next step.

## Send deploy events

Deploy requests and branch events come from a PlanetScale webhook. Squasher records each event as a
[deployment](/api-reference/deployments).

<Steps>
  <Step title="Add the webhook in PlanetScale">
    In the database settings in PlanetScale, add a webhook. Use the webhook URL that Squasher shows
    after you connect. Select the `deploy_request.*` events and `branch.ready`.
  </Step>

  <Step title="Save the signing secret in Squasher">
    PlanetScale shows a signing secret for the webhook. Squasher uses it to check each delivery.
    Paste it on the **PlanetScale** card, or pipe it to the CLI:

    ```bash theme={null}
    pbpaste | squasher integrations planetscale-webhook-secret --project "$SQUASHER_PROJECT_ID"
    ```

    The API request is `PUT /v1/projects/{project_id}/provider-connections/planetscale/webhook`
    with `{"secret": "..."}`. The secret has at least 8 characters.
  </Step>
</Steps>

| PlanetScale event | Deployment status |
| - | - |
| `deploy_request.opened`, `deploy_request.queued` | `pending` |
| `deploy_request.in_progress` | `building` |
| `deploy_request.schema_applied`, `branch.ready` | `ready` |
| `deploy_request.errored` | `failed` |
| `deploy_request.closed`, `deploy_request.reverted` | `canceled` |

Squasher drops a delivery when its `x-planetscale-signature` does not match the saved secret.

## What Squasher pulls

Every 5 minutes, Squasher reads the database and branch list and the Prometheus metrics endpoint of
each branch. It stores the metrics as OpenTelemetry metrics, for example
`planetscale_vtgate_query_executions_total`, `planetscale_vtgate_errors_total`,
`planetscale_vtgate_queries_duration`, `planetscale_mysql_replica_lag_seconds`, and
`planetscale_pods_cpu_util_percentages`. Squasher sends your service token only to
`https://api.planetscale.com`. It does not read a metrics endpoint on any other host.

Each branch metric has these resource attributes:

| Attribute | Value |
| - | - |
| `cloud.provider` | `planetscale` |
| `db.system.name` | The database engine, such as `mysql` |
| `db.namespace` | The database name |
| `deployment.environment.name` | The branch name |
| `squasher.source` | `planetscale` |

Query the metrics in **Metrics**, or see the databases and branches with their key metrics under
**Infrastructure**, on the **Providers** tab.

## Check the connection

```bash theme={null}
squasher integrations health --project "$SQUASHER_PROJECT_ID"
squasher integrations resources --project "$SQUASHER_PROJECT_ID" --provider planetscale
```

Each stream shows its freshness, the time of the last success, and the last error.

## Troubleshooting

| What you see | What to do |
| - | - |
| Freshness is `stale` | No pull has succeeded for 20 minutes. Read the last error in `squasher integrations health`. |
| Freshness is `never` | The first pull has not finished. Wait 5 minutes, then check again. |
| Error class `auth` (HTTP 401) | PlanetScale does not accept the token. Create a new token and connect again. |
| Error class `permission` (HTTP 403) | The token is missing a permission. Add the permissions in the table above, then connect again. |
| No deployments from deploy requests | Check that the webhook URL is correct and that the signing secret in Squasher matches the one in PlanetScale. |

## Next steps

<CardGroup cols={2}>
  <Card title="Provider connections" icon="https://mintcdn.com/nextbigthingllc/Fg5aclMlZNSrg_Y3/icons/entity/connection.svg?fit=max&auto=format&n=Fg5aclMlZNSrg_Y3&q=85&s=d0b3ee40d988fcded3129f8427d8e582" href="/integrations/provider-connections" width="24" height="24" data-path="icons/entity/connection.svg">
    Connect other providers and check their state.
  </Card>

  <Card title="Deployments API" icon="https://mintcdn.com/nextbigthingllc/Fg5aclMlZNSrg_Y3/icons/docs/api.svg?fit=max&auto=format&n=Fg5aclMlZNSrg_Y3&q=85&s=ad72f5da1d92bd1c152340d2b13ad254" href="/api-reference/deployments" width="24" height="24" data-path="icons/docs/api.svg">
    Read the deployments that deploy requests create.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.