TiDB Cloud
TiDB Self-Managed
Learning Center
Contact Us
​
Sign InStart for Free

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:

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:

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:

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

  1. Click Add Integration in the upper-right area of the TiDB Cloud Vercel integration page. The Add TiDB Cloud dialog is displayed.

  2. Select the scope of your integration in the drop-down list and click Continue.

  3. Select the Vercel projects to which the integration will be added and click Continue.

  4. Confirm the required permissions for integration and click Add Integration. Then you are directed to an integration page of the TiDB Cloud console.

  5. On the integration page, do the following:

    1. Select your target Vercel projects and click Next.
    2. Select your target TiDB Cloud organization and project.
    3. Select Cluster as your connection type.
    4. Select your target TiDB Cloud cluster. If the Cluster drop-down list is empty or you want to select a new TiDB Cloud Serverless cluster, click + Create Cluster in the list to create one.
    5. Select the database that you want to connect to. If the Database drop-down list is empty or you want to select a new Database, click + Create Database in the list to create one.
    6. Select the framework that your Vercel projects are using. If the target framework is not listed, select General. Different frameworks determine different environment variables.
    7. Choose whether to enable Branching to create new branches for preview environments.
    8. Click Add Integration and Return to Vercel.

Vercel Integration Page

  1. Get back to your Vercel dashboard, go to your Vercel project, click Settings > Environment Variables, and check whether the environment variables for your target TiDB cluster have been automatically added.

    If the following variables have been added, the integration is completed.

    General

    TIDB_HOST
TIDB_PORT
TIDB_USER
TIDB_PASSWORD
TIDB_DATABASE

    Prisma

    DATABASE_URL

    TiDB Cloud Serverless Driver

    DATABASE_URL

  1. Click Add Integration in the upper-right area of the TiDB Cloud Vercel integration page. The Add TiDB Cloud dialog is displayed.

  2. Select the scope of your integration in the drop-down list and click Continue.

  3. Select the Vercel projects to which the integration will be added and click Continue.

  4. Confirm the required permissions for integration and click Add Integration. Then you are directed to an integration page of the TiDB Cloud console.

  5. On the integration page, do the following:

    1. Select your target Vercel projects and click Next.
    2. Select your target TiDB Cloud organization and project.
    3. Select Data App as your connection type.
    4. Select your target TiDB Data App.
    5. Click Add Integration and Return to Vercel.

Vercel Integration Page

  1. Get back to your Vercel dashboard, go to your Vercel project, click Settings > Environment Variables, and check whether the environment variables for your target Data App have been automatically added.

    If the following variables have been added, the integration is completed.

    DATA_APP_BASE_URL
DATA_APP_PUBLIC_KEY
DATA_APP_PRIVATE_KEY

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.

    Vercel Integration Configuration Page

    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 Cloud Serverless cluster.

Connect with TiDB Cloud 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 Cloud 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 Cloud 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 Cloud 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.

    Vercel Preview_Deployment

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

      TiDB_Cloud_Branch_Check

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

      Preview_Envs

    3. TiDB Cloud integration will also register a blocking check to wait for the TiDB Cloud 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

  1. Get the connection information of your TiDB cluster.

    You can get the connection information from the connection dialog of your cluster. To open the dialog, go to the Clusters page of your project, click the name of your target cluster to go to its overview page, and then click Connect in the upper-right corner.

  2. Go to your Vercel dashboard > Vercel project > Settings > Environment Variables, and then declare each environment variable value according to the connection information of your TiDB cluster.

    Vercel Environment Variables

Here we use a Prisma application as an example. The following is a datasource setting in the Prisma schema file for a TiDB Cloud Serverless cluster:

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

In Vercel, you can declare the environment variables as follows:

  • Key = DATABASE_URL
  • Value = mysql://<User>:<Password>@<Endpoint>:<Port>/<Database>?sslaccept=strict

You can get the information of <User>, <Password>, <Endpoint>, <Port>, and <Database> in the TiDB Cloud console.

  1. Follow the steps in Manage a Data APP and Manage an Endpoint to create a Data App and its endpoints if you have not done that.

  2. Go to your Vercel dashboard > Vercel project > Settings > Environment Variables, and then declare each environment variable value according to the connection information of your Data App.

    Vercel Environment Variables

    In Vercel, you can declare the environment variables as follows.

    • Key = DATA_APP_BASE_URL
    • Value = <DATA_APP_BASE_URL>
    • Key = DATA_APP_PUBLIC_KEY
    • Value = <DATA_APP_PUBLIC_KEY>
    • Key = DATA_APP_PRIVATE_KEY
    • Value = <DATA_APP_PRIVATE_KEY>

    You can get the information of <DATA_APP_BASE_URL>, <DATA_APP_PUBLIC_KEY>, <DATA_APP_PRIVATE_KEY> from your Data Service page of the TiDB Cloud console.

Was this page helpful?

Request docs changesAsk questions on Discord