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

# PlanetScale Database

> Provision a PlanetScale (Vitess/MySQL) database with a production branch and an application password, via the official PlanetScale Terraform provider

Qovery creates it in your account with a third-party provider, using credentials you enter in the form, as a [Blueprint](https://www.qovery.com/docs/configuration/blueprints.md) service in one of your environments.

| | |
| - | - |
| Catalog name | `planetscale-database` |
| Category | Databases & Caches |
| Provider | EXTERNAL |
| Engine | terraform |
| Major versions (latest release) | `default` (1.0.7) |
| Source | [EXTERNAL/planetscale/default](https://github.com/Qovery/service-catalog/tree/EXTERNAL/planetscale/default/1.0.7/EXTERNAL/planetscale/default) |

> [!TIP]
>
> **New to this?** You don't need to know Terraform or Kubernetes. Qovery sets up PlanetScale Database in your account with the provider: you fill in a form, or paste the prompt below into your coding agent. The values it publishes, listed under Outputs, reach your other services as environment variables. Qovery tells you when a newer version of the Blueprint is available. Check the requirements in the Reference section before you start, and try it first in a development environment.

## Create it

> [tab] Console
>
> 1. Open the environment, then **New service** › **Blueprint**.
> 2. Find **PlanetScale Database** in the catalog and pick the major version.
> 3. Fill in the variables. Required ones are marked; the others use their defaults.
> 4. Create the service, and deploy it now or later.

> [tab] CLI and API
>
> List the catalog to get the latest tag, then create the service from it. `qovery api` signs the requests with your CLI session.
>
> ```bash theme={null}
> ORG_ID="REPLACE_WITH_ORGANIZATION_ID"
> ENV_ID="REPLACE_WITH_ENVIRONMENT_ID"
>
> qovery api "organization/$ORG_ID/blueprint/catalog" | jq '.. | objects | select(.name? == "planetscale-database")'
>
> cat > blueprint.json <<'EOF'
> {
>   "name": "planetscale-database",
>   "tag": "EXTERNAL/planetscale/default/1.0.7",
>   "icon": "app://qovery-console/planetscale",
>   "variables": [
>     {
>       "name": "planetscale_service_token_id",
>       "value": "REPLACE_WITH_PLANETSCALE_SERVICE_TOKEN_ID",
>       "is_secret": true
>     },
>     {
>       "name": "planetscale_service_token",
>       "value": "REPLACE_WITH_PLANETSCALE_SERVICE_TOKEN",
>       "is_secret": true
>     },
>     {
>       "name": "organization",
>       "value": "REPLACE_WITH_ORGANIZATION"
>     },
>     {
>       "name": "database_name",
>       "value": "REPLACE_WITH_DATABASE_NAME"
>     }
>   ],
>   "spec_overrides": {
>     "engine_version": "1.9.7"
>   }
> }
> EOF
> BLUEPRINT_ID=$(qovery api "environment/$ENV_ID/blueprint" --method POST --input - < blueprint.json | jq -r .id)
> rm blueprint.json   # it can hold secret values
> qovery api "blueprint/$BLUEPRINT_ID/deploy" --method POST
> qovery api "blueprint/$BLUEPRINT_ID"   # status of the latest deployment
> ```
>
> Replace each `REPLACE_WITH_` value. Add optional variables to `variables` the same way.

> [tab] Coding agent
>
> Paste this into Claude Code, Cursor, Codex or another coding agent with the [Qovery agent skills](https://www.qovery.com/docs/getting-started/quickstart/agent-skills.md) installed (`curl -fsSL https://skill.qovery.com/install.sh | bash`).
>
> ```text Prompt wrap theme={null}
> Add the Qovery Blueprint PlanetScale Database (planetscale-database) to one of my Qovery environments and deploy it. Ask me for planetscale_service_token_id, planetscale_service_token, organization and database_name.
> Ask me before deploying to a production environment.
> Docs: https://www.qovery.com/docs/configuration/blueprints/planetscale-database.md
> ```

You don't add any file to your repository. Qovery creates the Blueprint from the Console or the API.

## Variables and outputs

Generated from `qbm.yml` at `EXTERNAL/planetscale/default/1.0.7`, the manifest the Console form is built from.

> [accordion] All 8 variables
>
> | Name | Type | Required | Default | Secret | Description |
> | - | - | - | - | - | - |
> | `planetscale_service_token_id` | string | Yes | | Yes | PlanetScale service token ID |
> | `planetscale_service_token` | string | Yes | | Yes | PlanetScale service token |
> | `organization` | string | Yes | | | PlanetScale organization name |
> | `database_name` | string | Yes | | | Letters, digits, hyphens, underscores; max 64 chars. Destroying the last branch destroys the database. |
> | `branch_name` | string | | `main` | | Production branch name to create in the database |
> | `cluster_size` | string | | | | Vitess production cluster size (e.g. PS-10, PS-20). Empty = provider/plan default. |
> | `region` | string | | | | PlanetScale region slug for the branch (e.g. us-east). Empty = organization default. |
> | `role` | string | | `readwriter` | | Access role for the generated password |

Outputs become environment variables that other services in the environment can use. By default Qovery also creates an alias for each output, prefixed with the Blueprint's name; see [Aliases Qovery creates for outputs](https://www.qovery.com/docs/configuration/environment-variables.md#aliases-qovery-creates-for-outputs) for the naming rules and the cases where no alias is created.

> [accordion] All 8 outputs
>
> | Name | Secret | Description |
> | - | - | - |
> | `database_name` | | Database name |
> | `branch_name` | | Production branch name |
> | `mysql_address` | | MySQL address for the branch |
> | `mysql_edge_address` | | MySQL edge address for the branch |
> | `access_host_url` | | Connection host for the generated password |
> | `username` | | Generated database username |
> | `password` | Yes | Generated database password (only available at creation time) |
> | `connection_uri` | Yes | Ready-to-use MySQL connection URI with credentials embedded |

> [!WARNING]
>
> Secret variables and outputs are encrypted and masked in Qovery, but Terraform can also keep their values, and values derived from them, in its state. With the Qovery-managed state backend (the default), Qovery stores the state. If you use your own backend, protect it and keep state files out of version control.

## Reference

From the Blueprint's [README](https://github.com/Qovery/service-catalog/blob/EXTERNAL/planetscale/default/1.0.7/EXTERNAL/planetscale/default/README.md).

Provisions a [PlanetScale](https://planetscale.com/) (Vitess / MySQL) database with a production branch (`planetscale_vitess_branch`) and an application password (`planetscale_vitess_branch_password`), via the official `planetscale/planetscale` provider (`~> 1.0`).

> **No free tier.** PlanetScale removed its hobby/free plan; the cheapest paid plan starts around **\$39/month per database**. Deploying this blueprint is immediately billable.

### Credentials

A PlanetScale **service token**: `planetscale_service_token_id` + `planetscale_service_token` (both sensitive), supplied as variables (`credentials.default: env`). The token needs permission to create databases/branches and passwords in the organization.

### Variables

#### Required

| Name | Type | Sensitive | Description |
| - | - | - | - |
| `planetscale_service_token_id` | string | yes | Service token ID |
| `planetscale_service_token` | string | yes | Service token |
| `organization` | string | | PlanetScale organization name |
| `database_name` | string | | Database name (`^[a-zA-Z0-9_-]{1,64}$`) |

#### Optional

| Name | Type | Default | Description |
| - | - | - | - |
| `branch_name` | string | `main` | Production branch to create |
| `cluster_size` | string | | Vitess cluster size (e.g. `PS-10`). Unset = plan default. |
| `region` | string | | Region slug (e.g. `us-east`). Unset = org default. |
| `role` | string | `readwriter` | `reader`, `writer`, `readwriter`, or `admin` |

### Outputs

| Name | Sensitive | Description |
| - | - | - |
| `database_name` | | Database name |
| `branch_name` | | Production branch name |
| `mysql_address` | | MySQL address for the branch |
| `mysql_edge_address` | | MySQL edge address |
| `access_host_url` | | Connection host for the generated password |
| `username` | | Generated database username |
| `password` | yes | Generated password (only returned at creation) |
| `connection_uri` | yes | Ready-to-use MySQL URI with credentials embedded |

### Notes

* **The database is created implicitly with its first branch.** There is no separate database resource in the PlanetScale provider; destroying this blueprint deletes the branch and therefore the database and all its data — the same teardown semantics as the other managed-database blueprints in this catalog.
* The generated `password` is only returned by the API at creation time; it is surfaced as a sensitive output.
* Uses the **official v1** provider (a full rewrite of the deprecated v0); pinned `~> 1.0`.


## Related topics

- [Blueprints](https://www.qovery.com/docs/configuration/blueprints.md)
- [Create a Database](https://www.qovery.com/docs/getting-started/guides/getting-started/connect-database.md)
- [Databases](https://www.qovery.com/docs/configuration/database.md)
- [Scaleway MySQL](https://www.qovery.com/docs/configuration/blueprints/scaleway-mysql.md)
- [Scaleway Managed PostgreSQL](https://www.qovery.com/docs/configuration/blueprints/scaleway-managed-postgresql.md)


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