PlanetScale

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.

Create a service token

In PlanetScale, open your organization settings and create a service token.
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

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

Connect PlanetScale

Dashboard
CLI
API

Open your project and select Settings in the sidebar, then the Integrations tab.
On the PlanetScale card, select Connect.
Enter the organization name, the token ID, and the token, then save.

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.

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.

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\"}"

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.

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.

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:

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.

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

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.

Get started

Guides

Prerequisites

Create a service token

Connect PlanetScale

Send deploy events

What Squasher pulls

Check the connection

Troubleshooting

Next steps

Provider connections

Deployments API

​Prerequisites

​Create a service token

​Connect PlanetScale

​Send deploy events

​What Squasher pulls

​Check the connection

​Troubleshooting

​Next steps

Provider connections

Deployments API

Prerequisites

Create a service token

Connect PlanetScale

Send deploy events

What Squasher pulls

Check the connection

Troubleshooting

Next steps