Integrations /

PlanetScale Integration

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 connection object 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.

# 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.

  4. Select Connect to launch the authorization flow.

  5. Log in, if needed, to PlanetScale.

  6. 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.

  7. In the Netlify UI, select your Organization and Database.

  8. Assign PlanetScale branches to the Local development, Deploy Previews & Branch Deploys, and Production deploy contexts. If you’re not working with PlanetScale branches, set each context to main.

  9. Select Save.

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

The PlanetScale page in the Netlify UI indicates which organization and database the integration is configured to use.

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.

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, edit your configuration settings, and select Save to store the changes.

# 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 you connect your site and database 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.

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

npm install @netlify/planetscale @planetscale/database

Once the packages are installed, you can use the connection object to connect to your 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 type { Handler, HandlerEvent, HandlerContext } from "@netlify/functions";
import connection from "@netlify/planetscale";

export const handler: Handler = async function (event: HandlerEvent,
  context: HandlerContext) {

  const { body } = event;

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

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

  return connection.execute("INSERT INTO users (email, name) VALUES (?, ?)", [
  .then(() => {
    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