# PlanetScale > Connect PlanetScale so Ace reads your schema, deploy requests, Query Insights and bounded row counts, and can propose schema changes and backfills that a person approves. Source: https://tryace.dev/docs/integrations/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. | | | | --- | --- | | Category | Database | | Ace reads | Schema, deploy requests, Query Insights, databases and branches, and read-only SQL when you add a read-only password | | Ace can change | Schema changes through deploy requests, and bounded backfills when you add a write password. A person always approves. | | Opens incidents | No. Ace reads PlanetScale during investigations. | | Setup | Settings form | ## What Ace reads 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 change 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](https://tryace.dev/docs/concepts/actions-and-approvals). | Action | What it does | Needs | Undo | | --- | --- | --- | --- | | Schema change | Opens a deploy request from an existing development branch into the production branch, then deploys it. | Service token with `create_deploy_request` | Yes, during PlanetScale's revert window | | Schema revert | Reverts a deploy request inside PlanetScale's revert window. | Service token with `create_deploy_request` | No | | Backfill | Updates matching rows in batches, after a dry-run count. | Write SQL password, plus the read-only SQL host, username and password | No | ### How backfills work 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 incident 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 start - 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 permissions | Credential | Where to create it | Permissions | Why Ace needs it | | --- | --- | --- | --- | | Service token ID and service token (needed) | **Settings** > **Service tokens** | `read_database`, `read_branch`, `read_deploy_request` on the database | Read the database, schema, deploy requests and Query Insights. | | Same token (only for schema changes) | Same | `create_deploy_request` | Open, deploy and revert deploy requests. | | Read-only SQL host, username and password (optional) | The database's **Settings** > **Passwords** > **New password**, on the production branch | Role **Read-only** | Read-only SQL and row counts. The backfill dry run also needs it. | | Write SQL username and password (only for backfills) | Same | A role that can update the tables you backfill | Run approved, bounded backfills. | Ace doesn't detect `create_deploy_request` in advance, so Settings shows that the permission is checked when the action runs. ## Set up ### 1. Create a service token in PlanetScale 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 passwords 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 Ace 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 workload Open the workload in Ace and add PlanetScale under **Investigation sources**. ### 5. Optional: allow actions Turn on **Allow Ace to run approved actions**. ## Confirm it's working 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. Use a password with the reader role for read queries." **Re-validate** reruns the checks. ## Disconnect 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 steps - [Supabase](https://tryace.dev/docs/integrations/supabase) - [Actions and approvals](https://tryace.dev/docs/concepts/actions-and-approvals) - [All integrations](https://tryace.dev/docs/integrations)