PlanetScale Integration

This feature is in BETA.

PlanetScale is a MySQL-compatible serverless database powered by Vitess. PlanetScale features a branching workflow, which enables non-blocking schema changes. When you make changes to your schema, you create branches, or copies, of your database, instead of applying schema changes directly to production.

The PlanetScale Integration with Netlify enables you to connect your PlanetScale account to a Netlify site, assign database branches to different deploy contexts, and use the withPlanetscale function to insert a connection into your database call.

# Before you begin

To get started with PlanetScale on Netlify, make sure you have the following prerequisites:

  1. An account with PlanetScale.
  2. In your PlanetScale account, create a database.
  3. Optionally, create a database branch to take advantage of assigning database branches to different deploy contexts.
  4. Ensure you have a Netlify site on which you want to enable the integration.

Environment variables

When you connect your PlanetScale branches in the Netlify UI, environment variables for each PlanetScale branch sync automatically, enabling you to assign PlanetScale branches to specific deploy contexts.

To use the PlanetScale Integration, your site needs to use the new environment variable experience. If you’re using the classic experience, migrate your site to use the new experience.

# Get started with PlanetScale

Once you’ve created a PlanetScale account and a database to connect to a Netlify site, you can get started integrating PlanetScale with your site.

From the Netlify UI:

  1. From your team’s Sites list, select the site that you plan to use.

  2. From your site page, select Integrations > Database.

  3. In the PlanetScale section, select Enable, which launches the authorization page.

  4. Log in, if needed, to PlanetScale.

  5. Configure your account access, such as the PlanetScale organization you’re granting Netlify access to. Then, select Authorize access to complete authorization. This reroutes you back to the Netlify UI.

  6. In the Netlify UI, select your organization and database.

  7. Assign PlanetScale branches to the Production, Deploy Preview, and Local Development deploy contexts. If you’re not working with PlanetScale branches, set each context to main.

  8. Select Connect.

Here is an example of configurations for organization, database, and branches when a connection is successful:

The PlanetScale page in the Netlify UI includes a configured database branch for the production, Deploy Preview, and local development deploy contexts.

In the example above, the dev database branch is assigned to the Deploy Preview and Local Development deploy contexts, and main is assigned to Production. If you’re not using database branches, your configuration may assign the main database to every deploy context.

If you encounter an error establishing a connection, your site might be using the classic environment variables experience. Migrate your site to the new environment variable experience to continue.

You can make changes to your PlanetScale Integration settings directly in the Netlify UI from the Integrations tab for your site. Select Database > PlanetScale > View. Then, select Edit to edit your configuration settings.

# User-level authentication

The PlanetScale Integration authenticates at the user-level in the Netlify UI. When you collaborate on a team, each user needs to enable the PlanetScale Integration and follow the authentication steps above to connect to PlanetScale.

# Create a function to call PlanetScale

Once your site and database are connected in the Netlify UI, you can connect to and make calls to your PlanetScale database from your code with Netlify Functions. For example, if your site contains a sign-up form that collects a user’s name and email address, that data can be sent to your PlanetScale database to populate a user table. Use the withPlanetscale function to make these calls from your code.

To get started, install the necessary dependencies to use the PlanetScale Integration.

npm install @netlify/planetscale @planetscale/database

Once the packages are installed, the withPlanetscale function enables you to connect to your database with the appropriate context for your environment.

In the example below, the planetscale property on the context object contains the connection object. This enables a connection to the database using the credentials stored in environment variables. Once connected, the SQL command executes to insert the email and name properties into the users table of the PlanetScale database.

import { Handler } from "@netlify/functions";
import { withPlanetscale } from "@netlify/planetscale";

export const handler: Handler = withPlanetscale(async (event, context) => {
  const {
    planetscale: { connection },
  } = context;

  const { body } = event;

  if (!body) {
    return {
      statusCode: 400,
      body: "Missing body",

  const { email, name } = JSON.parse(body);

  await connection.execute("INSERT INTO users (email, name) VALUES (?, ?)", [

  return {
    statusCode: 201,

# Test locally

You can use Netlify CLI to test your function locally.

  1. Ensure you have the latest version of Netlify CLI installed:

    npm install netlify-cli -g
  2. Launch Netlify Dev to start a development environment that pulls in the necessary context needed to connect to your database:

    netlify dev
  3. Visit localhost:8888 to launch your site locally. From here, you can test the action that triggers your database call.

Note that testing locally pulls in the environment variables for the PlanetScale branch that’s connected to your local development environment. This enables you to test a development branch of your database, rather than a production branch, when you test locally.

# More resources

# Feedback

We welcome your feedback on the PlanetScale Integration. Fill out our survey to share your thoughts or ideas.