集成 TiDB Cloud 与 Vercel
Vercel 是一个面向前端开发者的平台,提供创新者在灵感迸发时所需的速度与可靠性。
将 TiDB Cloud 与 Vercel 结合使用,可以让你基于兼容 MySQL 的关系模型更快地构建新的前端应用,并借助具备高可用性、可扩展性以及最高级别数据隐私和安全的平台,放心地扩展你的应用。
本指南介绍了如何通过以下任一方式将你的 TiDB Cloud 集群连接到 Vercel 项目:
对于上述两种方式,TiDB Cloud 都提供了以下可编程连接数据库的选项:
- 集群:通过直连或 serverless driver 将你的 TiDB Cloud 集群连接到 Vercel 项目。
- 数据应用(Data App):通过一组 HTTP 端点访问 TiDB Cloud 集群的数据。
前置条件
在连接前,请确保满足以下前置条件。
一个 Vercel 账号和一个 Vercel 项目
你需要在 Vercel 中拥有一个账号和一个项目。如果还没有,请参考以下 Vercel 文档创建:
- 创建个人账号 或 创建团队。
- 在 Vercel 中创建项目,如果你还没有可部署的应用,可以使用 TiDB Cloud Starter Template 进行体验。
一个 Vercel 项目只能连接一个 TiDB Cloud 集群。如需更换集成,需先断开当前集群,再连接新集群。
一个 TiDB Cloud 账号和一个 TiDB 集群
你需要在 TiDB Cloud 中拥有一个账号和一个集群。如果还没有,请参考以下内容创建:
要通过 TiDB Cloud Vercel 集成与 Vercel 集成,你需要是 TiDB Cloud 组织的 Organization Owner
角色,或目标项目的 Project Owner
角色。更多信息参见 用户角色。
一个 TiDB Cloud 集群可以连接多个 Vercel 项目。
一个数据应用(Data App)及其端点
如果你希望通过 数据应用(Data App) 连接 TiDB Cloud 集群,需要提前在 TiDB Cloud 中准备好目标 Data App 及其端点。如果还没有,请参考以下步骤创建:
- 在 TiDB Cloud 控制台中,进入项目的 数据服务 页面。
- 为项目创建 Data App。
- 将 Data App 关联到目标 TiDB Cloud 集群。
- 管理端点,以便自定义执行 SQL 语句。
一个 Vercel 项目只能连接一个 TiDB Cloud Data App。如需更换 Data App,需先断开当前 App,再连接新 App。
通过 TiDB Cloud Vercel 集成连接
要通过 TiDB Cloud Vercel 集成连接,请前往 Vercel 的集成市场中的 TiDB Cloud 集成 页面。使用此方法,你可以选择要连接的集群,TiDB Cloud 会自动为你的 Vercel 项目生成所有必要的环境变量。
集成流程
详细步骤如下:
在 TiDB Cloud Vercel 集成 页面右上角点击 Add Integration,弹出 Add TiDB Cloud 对话框。
在下拉列表中选择集成范围,点击 Continue。
选择要添加集成的 Vercel 项目,点击 Continue。
确认集成所需权限,点击 Add Integration。随后会跳转到 TiDB Cloud 控制台的集成页面。
在集成页面,按以下步骤操作:
- 选择目标 Vercel 项目,点击 Next。
- 选择目标 TiDB Cloud 组织和项目。
- 选择 Cluster 作为连接类型。
- 选择目标 TiDB Cloud 集群。如果 Cluster 下拉列表为空,或你想选择新的 TiDB Cloud Serverless 集群,可点击列表中的 + Create Cluster 创建。
- 选择要连接的数据库。如果 Database 下拉列表为空,或你想选择新的数据库,可点击列表中的 + Create Database 创建。
- 选择 Vercel 项目所用的框架。如果目标框架未列出,选择 General。不同框架会生成不同的环境变量。
- 选择是否启用 Branching,以为预览环境创建新分支。
- 点击 Add Integration and Return to Vercel。
返回 Vercel 控制台,进入你的 Vercel 项目,点击 Settings > Environment Variables,检查目标 TiDB 集群的环境变量是否已自动添加。
如果以下变量已添加,说明集成完成。
General
TIDB_HOST TIDB_PORT TIDB_USER TIDB_PASSWORD TIDB_DATABASEPrisma
DATABASE_URLTiDB Cloud Serverless Driver
DATABASE_URL
在 TiDB Cloud Vercel 集成 页面右上角点击 Add Integration,弹出 Add TiDB Cloud 对话框。
在下拉列表中选择集成范围,点击 Continue。
选择要添加集成的 Vercel 项目,点击 Continue。
确认集成所需权限,点击 Add Integration。随后会跳转到 TiDB Cloud 控制台的集成页面。
在集成页面,按以下步骤操作:
- 选择目标 Vercel 项目,点击 Next。
- 选择目标 TiDB Cloud 组织和项目。
- 选择 Data App 作为连接类型。
- 选择目标 TiDB Data App。
- 点击 Add Integration and Return to Vercel。
返回 Vercel 控制台,进入你的 Vercel 项目,点击 Settings > Environment Variables,检查目标 Data App 的环境变量是否已自动添加。
如果以下变量已添加,说明集成完成。
DATA_APP_BASE_URL DATA_APP_PUBLIC_KEY DATA_APP_PRIVATE_KEY
配置连接
如果你已安装 TiDB Cloud Vercel 集成,可以在集成内添加或移除连接。
在 Vercel 控制台点击 Integrations。
在 TiDB Cloud 条目中点击 Manage。
点击 Configure。
点击 Add Link 或 Remove 以添加或移除连接。
当你移除连接时,集成流程设置的环境变量也会从 Vercel 项目中移除。但此操作不会影响 TiDB Cloud Serverless 集群中的数据。
使用 TiDB Cloud Serverless 分支功能连接
Vercel 的 Preview Deployments 功能允许你在不合并到 Git 项目的生产分支的情况下,在实时部署中预览应用变更。结合 TiDB Cloud Serverless 分支,你可以为 Vercel 项目的每个分支创建一个新的实例,从而在不影响生产数据的情况下预览应用变更。
要启用 TiDB Cloud Serverless 分支功能,需要在 TiDB Cloud Vercel 集成流程中确保:
- 选择 Cluster 作为连接类型。
- 启用 Branching,为预览环境创建新分支。
在你将变更推送到 Git 仓库后,Vercel 会触发预览部署。TiDB Cloud 集成会自动为该 Git 分支创建 TiDB Cloud Serverless 分支并设置环境变量。详细步骤如下:
在你的 Git 仓库中创建新分支。
cd tidb-prisma-vercel-demo1 git checkout -b new-branch添加一些变更并推送到远程仓库。
Vercel 会为新分支触发预览部署。
部署过程中,TiDB Cloud 集成会自动创建与 Git 分支同名的 TiDB Cloud Serverless 分支。如果该分支已存在,则跳过此步骤。
当 TiDB Cloud Serverless 分支就绪后,TiDB Cloud 集成会在 Vercel 项目的预览部署中设置环境变量。
TiDB Cloud 集成还会注册一个阻塞检查,等待 TiDB Cloud Serverless 分支就绪。你可以手动重新运行该检查。
检查通过后,你可以访问预览部署查看变更效果。
通过手动设置环境变量连接
获取 TiDB 集群的连接信息。
你可以在集群的连接对话框中获取连接信息。进入项目的 Clusters 页面,点击目标集群名称进入概览页,然后点击右上角的 Connect。
进入 Vercel 控制台 > Vercel 项目 > Settings > Environment Variables,根据 TiDB 集群的连接信息声明每个环境变量的值。
这里以 Prisma 应用为例,以下是 TiDB Cloud Serverless 集群在 Prisma schema 文件中的 datasource 配置:
datasource db {
provider = "mysql"
url = env("DATABASE_URL")
}
在 Vercel 中,你可以这样声明环境变量:
- Key =
DATABASE_URL
- Value =
mysql://<User>:<Password>@<Endpoint>:<Port>/<Database>?sslaccept=strict
你可以在 TiDB Cloud 控制台获取 <User>
、<Password>
、<Endpoint>
、<Port>
和 <Database>
的信息。
按照 管理 Data APP 和 管理 Endpoint 的步骤创建 Data App 及其端点(如尚未创建)。
进入 Vercel 控制台 > Vercel 项目 > Settings > Environment Variables,根据 Data App 的连接信息声明每个环境变量的值。
在 Vercel 中,你可以这样声明环境变量:
- 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>
你可以在 TiDB Cloud 控制台的 Data Service 页面获取
<DATA_APP_BASE_URL>
、<DATA_APP_PUBLIC_KEY>
、<DATA_APP_PRIVATE_KEY>
的信息。- Key =