PlanetScale

Ace reads PlanetScale as evidence during investigations. It looks at the schema of the tables an error points at, recent schema changes, slow or heavy query patterns, and row counts that test a hypothesis.

What Ace readsCopy Anchor Link

Ace reads PlanetScale while it investigates a workload that lists it under Investigation sources or routes its alerts. It reads one database and its production branch, main unless you set another.

The service token lets Ace read:

• CREATE TABLE statements of the production branch.
• Recent deploy requests with their state and deploy time.
• Query Insights patterns for the production branch, normalized so they never include literal values. Query Insights must be on for the database.

If you add the optional read-only SQL password, Ace runs one SELECT, SHOW, DESCRIBE or EXPLAIN statement per request and gets at most 100 rows back. It refuses multiple statements and statements that write files, lock rows or stall the database.

The password itself is what stops writes. Ace checks that it has PlanetScale's reader role on the production branch, so the database refuses any write sent with it.

For the System Map, Ace reads your databases and branches.

What Ace can changeCopy Anchor Link

Every PlanetScale action needs a person's approval and never runs automatically, whatever your policy says. Ace proposes them only after an admin turns on Allow Ace to run approved actions for the connection. See Actions and approvals.

How backfills workCopy Anchor Link

Ace builds the backfill UPDATE from a table name, 1 to 10 columns to set, and 1 to 10 conditions (IS NULL or equals). It validates column names and escapes values, and it never runs free-form SQL.

1. Dry run. Ace counts matching rows with the read-only password. If none match, or more match than the limit you approve, Ace blocks the backfill.
2. Approval. You see the exact UPDATE and row count, and you set Rows per batch (1 to 1,000), Most rows to update (1 to 100,000) and the wait between stages.
3. Batches. Ace runs the update with the write password, one batch at a time. One condition must be on a column the backfill sets, so updated rows stop matching and each batch reaches new rows.

A backfill can't be undone, and it can't run without a write SQL password. Ace doesn't check that password's role, so give it only the access backfills need.

What opens an incidentCopy Anchor Link

Nothing. PlanetScale has no webhook, and Ace doesn't poll it. To use it, add it to a workload's Investigation sources.

Schema changes made outside Ace don't join the change ledger. Ace reads recent deploy requests during an investigation instead.

Before you startCopy Anchor Link

• The admin role in Ace.
• Permission to create service tokens and passwords for the database in PlanetScale.
• Query Insights turned on for the database, if you want Ace to read it.

Credentials and permissionsCopy Anchor Link

Ace doesn't detect create_deploy_request in advance, so Settings shows that the permission is checked when the action runs.

Set upCopy Anchor Link

1. Create a service token in PlanetScaleCopy Anchor Link

1. Open Settings > Service tokens and choose New service token. Name it Ace and select Create service token.
2. Copy the token ID and the token right away, because PlanetScale can't show either one again.
3. Select Edit token permissions > Add database access and pick the database. Tick read_database, read_branch and read_deploy_request, plus create_deploy_request for schema changes. Select Save permissions.

2. Optional: create SQL passwordsCopy Anchor Link

1. In the database's Settings > Passwords, choose New password on the production branch with role Read-only. Copy the host, username and password. PlanetScale shows the password once.
2. Only for backfills, create a second password with write access on the same branch. Copy its username and password.

3. Connect PlanetScale in AceCopy Anchor Link

1. Open Settings > Data sources and choose PlanetScale.

2. Fill in the form:

   Field	What to enter
   Service token ID	The token ID.
   Service token	The token.
   Organization	Your PlanetScale organization name.
   Database	The database name.
   Production branch	Optional. Defaults to main.
   Read-only SQL host	Optional. The host from the read-only password. It ends in .psdb.cloud.
   Read-only SQL username	Optional.
   Read-only SQL password	Optional.
   Write SQL username	Optional. Only for approved, bounded backfills.
   Write SQL password	Optional.

3. Select Connect PlanetScale. Before it saves, Ace checks the token and, if you entered a read-only password, checks that the password works and has the reader role.

4. Add PlanetScale to a workloadCopy Anchor Link

Open the workload in Ace and add PlanetScale under Investigation sources.

5. Optional: allow actionsCopy Anchor Link

Turn on Allow Ace to run approved actions.

Confirm it's workingCopy Anchor Link

The connection runs database_read, schema_read and deploy_requests_read for the service token. For a read-only password it also runs sql_read and sql_read_role. A password with another role fails with "The read password has the <role> role. Use a password with the reader role for read queries." Re-validate reruns the checks.

DisconnectCopy Anchor Link

1. In Ace, open the PlanetScale connection under Settings > Data sources and select Disconnect. To stop actions and keep the connection, turn off Allow Ace to run approved actions instead.
2. In PlanetScale, delete the Ace service token and any SQL passwords you created for Ace. Ace creates nothing else in PlanetScale.

Next stepsCopy Anchor Link

• Supabase
• Actions and approvals
• All integrations