> For the complete documentation index, see [llms.txt](https://docs.release.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.release.com/integrations/integrations-overview/planetscale-integration.md).

# PlanetScale integration

How to set up the Release PlanetScale integration for instant databases

Release integrates with [PlanetScale](https://planetscale.com) to provision databases for your ephemeral environments. PlanetScale supports both MySQL and PostgreSQL engines. With PlanetScale, Release can automatically create database branches, giving each environment its own isolated database instance.

## Prerequisites

Before setting up the PlanetScale integration in Release, you'll need:

1. A PlanetScale account (sign up at [app.planetscale.com](https://app.planetscale.com))
2. A verified email address on your PlanetScale account
3. A PlanetScale organization with at least one database created
4. A PlanetScale service token with the appropriate permissions

## Step 1: Create a PlanetScale Account and Database

1. Sign up or log in at [app.planetscale.com](https://app.planetscale.com).
2. Verify your email address by clicking the confirmation link sent to your inbox.
3. Create a new database (or use an existing one) in your PlanetScale organization.

![PlanetScale organization overview showing the testing database](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-021b2022d59c6f335bad1705d69e0d3f945d2cbf%2Fplanetscale-org-overview.png?alt=media)

## Step 2: Create a Service Token in PlanetScale

Release connects to PlanetScale using a **service token**. You'll need to create one with the right permissions.

1. In PlanetScale, navigate to your organization **Settings** > **Service tokens**.

![PlanetScale service tokens page](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-8108c38e5add30ab86f20525cdb4b7e7644c20fc%2Fplanetscale-service-tokens.png?alt=media)

2. Click **New service token**.
3. Enter a name for the token (e.g., `release-integration`) and set the expiration policy. For production use, "No expiration" is typical.
4. Click **Create service token**.
5. **Important:** Copy both the **ID** and **Token** values immediately. The token will not be shown again after this step.

![Service token ID and token values - copy these before proceeding](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-2b2778c083ffa2381dc79ad2ae7b873ce540b45c%2Fplanetscale-token-created.png?alt=media)

{% hint style="warning" %}
The service token value is only displayed once. Make sure to copy it before closing the dialog.
{% endhint %}

## Step 3: Configure Service Token Permissions

After creating the token, you need to assign the correct permissions. Click **Continue to token permissions** to configure access.

### Required Permissions

For the Release integration to work correctly, the service token needs the following permissions on your databases:

**Database permissions:**

* `read_database` — List and get information about databases
* `write_database` — Create connection credentials (passwords and roles)

**Branch permissions:**

* `create_branch` — Create database branches for environments
* `read_branch` — Check branch status during setup
* `delete_branch` — Clean up branches during teardown
* `connect_branch` — Connect to a branch to generate credentials
* `delete_branch_password` — Clean up credentials during teardown

**Backup permissions (optional — only needed if restoring from backups):**

* `read_backups` — List available backups

{% hint style="info" %}
You can set these permissions at the organization level using **Permissions for all databases**, which applies to all current and future databases. Alternatively, you can grant access to specific databases only.
{% endhint %}

![Service token permissions configuration showing database, branch, and backup permissions selected](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-281a20930ec281b0051a6c70c880e44b28380f66%2Fplanetscale-permissions.png?alt=media)

Click **Save permissions** when done.

![Service token with permissions saved](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-7664cac21b23c62d5ceac3a789f62948179009d7%2Fplanetscale-permissions-saved.png?alt=media)

## Step 4: Install the PlanetScale Integration in Release

1. In the Release UI, navigate to **Configuration** > **Integrations** (accessible at `/workspaces/<workspace-id>/configuration/integrations`).

![Release Integrations page showing available integrations](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-915932cee6e935a1b32d40976a83fec469a168ab%2Frelease-integrations-list.png?alt=media)

2. Find **PlanetScale** under the **Available** section and click on it.
3. Click **Install PlanetScale**.

![PlanetScale integration page with Install button](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-bf3d6a22ed0c982f8b931ac1e47bc3f85c025849%2Frelease-planetscale-install-button.png?alt=media)

4. Fill in the integration form with the credentials from your PlanetScale service token:

| Field                  | Value                                             | Description                                            |
| ---------------------- | ------------------------------------------------- | ------------------------------------------------------ |
| **Organization Name**  | Your PlanetScale org name (e.g., `david-release`) | The organization name from your PlanetScale account    |
| **Project Identifier** | Service token ID (e.g., `oul2eenoq9bt`)           | The **ID** from the service token you created          |
| **Access Token**       | Service token value (e.g., `pscale_tkn_...`)      | The **Token** value from the service token you created |

![Install PlanetScale form filled with credentials](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-43e1ae9c637cfa944702a7b4d6b119a202644910%2Frelease-planetscale-install-form.png?alt=media)

5. Click **Install Integration**.
6. The integration is now installed and will appear under the **Installed** section on the Integrations page.

![PlanetScale now showing as an installed integration](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-85ed6672879b1d7b54efea9a6ad1a891185295d7%2Frelease-planetscale-installed.png?alt=media)

## Step 5: Create a PlanetScale Dataset

Once the integration is installed, you can create datasets that use PlanetScale as the database provider.

1. Navigate to **Configuration** > **Datasets**.
2. Click **Create Dataset**. If the PlanetScale integration is installed, you'll see a **PlanetScale** tab alongside the **Cloud Provider** tab.
3. Select the **PlanetScale** tab.
4. Enter a **Dataset Name** (3–50 characters, lowercase letters, numbers, and hyphens).
5. Select a **PlanetScale database** from the dropdown. This lists all databases available to your service token.
6. Set a **Pool master password** or click the generate button to auto-generate one.
7. Configure the **Number of available databases** (how many branches to keep in the pool).
8. Click **Create Dataset**.

![PlanetScale dataset creation form with database selected and password configured](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-93e3c74777f8e46ce4c356507186e67502ea3ffc%2Frelease-create-planetscale-dataset.png?alt=media)

## How It Works

When Release creates an ephemeral environment that uses a PlanetScale dataset:

1. Release creates a **new database branch** from the current state of the selected database.
2. The branch is monitored until it reaches a **ready** state.
3. Connection credentials are generated and automatically injected as **environment variables** into your services.
4. When the environment is torn down, the branch is deleted to clean up resources.

### Environment Variables

The following environment variables are automatically set for services using PlanetScale datasets. The prefix is derived from the dataset name (uppercased, with hyphens replaced by underscores).

For example, a dataset named `my-app` would produce:

| Variable                       | Description                      |
| ------------------------------ | -------------------------------- |
| `MY_APP_DB_POOL_HOST`          | PlanetScale connection hostname  |
| `MY_APP_DB_POOL_PASS`          | Database password                |
| `MY_APP_DB_POOL_USER`          | Database username                |
| `MY_APP_DB_POOL_DATABASE_NAME` | Source PlanetScale database name |
| `MY_APP_DB_POOL_NAME`          | Branch name created by Release   |

## Updating the Integration

To update your PlanetScale credentials:

1. Go to **Configuration** > **Integrations** > **PlanetScale**.
2. Click **Actions** > **Configure**.
3. Update the Organization Name, Project Identifier, or Access Token as needed.
4. Click **Save**.

## Troubleshooting

### Integration won't connect

* Verify your service token hasn't expired
* Ensure the service token has the required permissions (database, branch, and backup access)
* Check that the Organization Name matches exactly (case-sensitive)

### Database branches not creating

* Confirm your source database has at least one backup/snapshot available
* Verify the service token has `create_branch` and `restore_backup` permissions
* Check that your PlanetScale plan supports the number of branches you need

### Connection issues in environments

* PlanetScale requires SSL connections — ensure your application is configured to use SSL
* Verify your application's database driver matches the engine of your PlanetScale database (MySQL or PostgreSQL)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.release.com/integrations/integrations-overview/planetscale-integration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.