Netlify Docs
Ask Netlify

Contact

Integrate & extend /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

As a Team Owner, you can install the PlanetScale integration for your team to use:

  1. In the Netlify UI, navigate to the

    Extensions
    page for your team.

  2. Search for PlanetScale and select it in the search results.

  3. On the details page, select Install.

  4. From your team’s Sites list, select the site you plan to use with PlanetScale, and navigate to

    Site configuration General PlanetScale
    .

  5. Select Connect to launch the authorization flow.

  6. Log in, if needed, to PlanetScale.

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

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

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

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

# 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 follow the authentication steps above to connect to PlanetScale (steps 4-10).

# 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 connection from "@netlify/planetscale";

export default async (req: Request) => {
  
  const { email, name } = await req.json();

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

  return new Response("User created", { status: 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.

# Modify your configuration

To update the PlanetScale configuration settings for your site:

  1. In the Netlify UI, navigate to
    Site configuration General PlanetScale
    for the site you want to edit.
  2. Update your configuration and then select Save.

Alternatively, you can update the environment variables directly.

# Uninstall the integration

As a Team Owner, to uninstall the PlanetScale integration:

  1. In the Netlify UI, navigate to the
    Extensions
    page for your team.
  2. Search for PlanetScale and select it in the search results.
  3. On the details page, navigate to the Danger zone section, and then select Uninstall this extension.

# More resources