Integrate TiDB Cloud with Vercel

Vercel is a platform for frontend developers, providing the speed and reliability innovators need to create at the moment of inspiration.

Using TiDB Cloud with Vercel enables you to build new frontend applications faster with a MySQL-compatible relational model and grow your app with confidence with a platform built for resilience, scale, and the highest levels of data privacy and security.

This guide describes how to connect your TiDB Cloud clusters to Vercel projects using one of the following methods:

• Connect via the TiDB Cloud Vercel integration
• Connect via manually configuring environment variables

For both of the preceding methods, TiDB Cloud provides the following options for programmatically connecting to your database:

• Cluster: connect your TiDB Cloud cluster to your Vercel project with direct connections or serverless driver.
• Data App: access data of your TiDB Cloud cluster through a collection of HTTP endpoints.

Prerequisites

Before connection, make sure the following prerequisites are met.

A Vercel account and a Vercel project

You are expected to have an account and a project in Vercel. If you do not have any, refer to the following Vercel documents to create one:

• Creating a new personal account or Creating a new team.
• Creating a project in Vercel, or if you do not have an application to deploy, you can use the TiDB Cloud Starter Template to have a try.

One Vercel project can only connect to one TiDB Cloud cluster. To change the integration, you need to first disconnect the current cluster and then connect to a new cluster.

A TiDB Cloud account and a TiDB cluster

You are expected to have an account and a cluster in TiDB Cloud. If you do not have any, refer to the following to create one:

• Create a TiDB Serverless cluster

  Note

  The TiDB Cloud Vercel integration supports creating TiDB Serverless clusters. You can also create one later during the integration process.

• Create a TiDB Dedicated cluster

  Note

  For TiDB Dedicated clusters, make sure that the traffic filter of the cluster allows all IP addresses (set to 0.0.0.0/0) for connection, because Vercel deployments use dynamic IP addresses.

To integrate with Vercel via the TiDB Cloud Vercel Integration, you are expected to be in the Organization Owner role of your organization or the Project Owner role of the target project in TiDB Cloud. For more information, see User roles.

One TiDB Cloud cluster can connect to multiple Vercel projects.

A Data App and endpoints

If you want to connect to your TiDB Cloud cluster via a Data App, you are expected to have the target Data App and endpoints in TiDB Cloud in advance. If you do not have any, refer to the following to create one:

1. In the TiDB Cloud console, go to the Data Service page of your project.
2. Create a Data App for your project.
3. Link the Data App to the target TiDB Cloud cluster.
4. Manage endpoints so that you can customize them to execute SQL statements.

One Vercel project can only connect to one TiDB Cloud Data App. To change the Data App for your Vercel project, you need to first disconnect the current App and then connect to a new App.

Connect via the TiDB Cloud Vercel integration

To connect via the TiDB Cloud Vercel integration, go to the TiDB Cloud integration page from the Vercel's Integrations Marketplace. Using this method, you can choose which cluster to connect to, and TiDB Cloud will automatically generate all the necessary environment variables for your Vercel projects.

Integration workflow

The detailed steps are as follows:

• Cluster
• Data App

Configure connections

If you have installed TiDB Cloud Vercel integration, you can add or remove connections inside the integration.

1. In your Vercel dashboard, click Integrations.

2. Click Manage in the TiDB Cloud entry.

3. Click Configure.

4. Click Add Link or Remove to add or remove connections.

   

   When you remove a connection, the environment variables set by the integration workflow are removed from the Vercel project, too. However, this action does not affect the data of the TiDB Serverless cluster.

Connect with TiDB Serverless branching

Vercel's Preview Deployments feature allows you to preview changes to your app in a live deployment without merging those changes to your Git project's production branch. With TiDB Serverless Branching, you can create a new instance for each branch of your Vercel project. This allows you to preview app changes in a live deployment without affecting your production data.

To enable TiDB Serverless Branching, you need to ensure the following in the TiDB Cloud Vercel integration workflow:

1. Select Cluster as your connection type.
2. Enable Branching to create new branches for preview environments.

After you push changes to the Git repository, Vercel will trigger a preview deployment. TiDB Cloud integration will automatically create a TiDB Serverless branch for the Git branch and set environment variables. The detailed steps are as follows:

1. Create a new branch in your Git repository.

   cd tidb-prisma-vercel-demo1
   git checkout -b new-branch
   

2. Add some changes and push the changes to the remote repository.

3. Vercel will trigger a preview deployment for the new branch.

   

   1. During the deployment, TiDB Cloud integration will automatically create a TiDB Serverless branch with the same name as the Git branch. If the TiDB Serverless branch already exists, TiDB Cloud integration will skip this step.

      

   2. After the TiDB Serverless branch is ready, TiDB Cloud integration will set environment variables in the preview deployment for the Vercel project.

      

   3. TiDB Cloud integration will also register a blocking check to wait for the TiDB Serverless branch to be ready. You can rerun the check manually.

4. After the check is passed, you can visit the preview deployment to see the changes.

Connect via manually setting environment variables

• Cluster
• Data App

datasource db {
    provider = "mysql"
    url      = env("DATABASE_URL")
}