TiDB Cloud Serverless Driver for JavaScript

This driver is for serverless and edge compute platforms that require HTTP external connections, such as Vercel Edge Functions or Cloudflare Workers.

There are three ways to use the driver:

1. Stateless connection (default): each query is independent, ideal for edge environments with short-lived, frequently created connections.
2. Stateful connection (experimental): use it when you require session.
3. Transaction (experimental): use it when you require interactive transaction.

Usage

Install

You can install the driver with npm:

npm install @tidbcloud/serverless

Stateless Connection

To query from TiDB Serverless, you need to create a connection first. Then you can use the connection to execute raw SQL queries.

Overlapping operations on the same connection are rejected. Await each operation before starting another, or use separate connections for concurrent queries. Each transaction or stateful handle should belong to one logical unit of work; sharing a handle across users does not provide tenant isolation.

import { connect } from '@tidbcloud/serverless'

const conn = connect({url: 'mysql://username:password@host/database'})
const results = await conn.execute('select * from test where id = ?',[1])

Placeholders (? or named :name) are replaced only outside quoted strings, quoted identifiers, and comments. Do not quote placeholders. For a LIKE pattern, use conn.execute('SELECT * FROM test WHERE name LIKE ?', ['%search%']). A query that has parameters must not contain executable comments (/*! ... */ or /*T![...] ... */); execute throws an error for such a query. Queries without parameters are sent unchanged.

Stateful Connection (experimental)

If you want to keep session state across multiple queries, create a stateful connection. Remember to call close() to release the connection, or you may reach the connection limits.

Note:

Connections idle for 10 minutes will be closed automatically. Overlapping queries or close() on the same stateful connection are rejected. Await each operation before starting another.

import { connect } from '@tidbcloud/serverless'

const conn = connect({url: 'mysql://username:password@host/database'})
const stateful = await conn.persist()

try {
  const r1 = await stateful.execute('use db2')
  const r2 = await stateful.execute('select * from test where id = ?', [2])
} finally {
  await stateful.close()
}

Transaction (experimental)

You can also perform interactive transactions with the serverless driver. For example:

Note:

Transactions idle for 10 minutes will be rolled back automatically if it has not been committed or rolled back. Overlapping queries, commit(), or rollback() on the same transaction are rejected. Await each operation before starting another.

import { connect } from '@tidbcloud/serverless'

const conn = connect({url: 'mysql://username:password@host/database'})
const tx = await conn.begin()

try {
  await tx.execute('insert into test values (1)')
  await tx.execute('select * from test')
  await tx.commit()
}catch (err) {
  await tx.rollback()
  throw err
}

Edge example

The serverless driver is suitable for the edge environments. See how to use it with Vercel Edge Functions:

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { connect } from '@tidbcloud/serverless'
export const runtime = 'edge'

export async function GET(request: NextRequest) {
  const conn = connect({url: process.env.DATABASE_URL})
  const result = await conn.execute('show tables')
  return NextResponse.json({result});
}

See TiDB Cloud Serverless Driver documentation to learn more.

MCP for AI Agent

Do not use it in production.

{
  "mcpServers": {
    "tidbcloud-serverless-mcp": {
      "command": "npx",
      "args": ["-y", "@tidbcloud/serverless-mcp"],
      "env": {
        "TIDB_DATABASE_URL": "mysql://<user>:<password>@<host>/<database>"
      }
    }
  }
}

Configuration

See Configure TiDB Cloud Serverless Driver.

host must be a plain DNS hostname, without a scheme, port, userinfo, or path. Custom domains are supported, and the existing http- gateway prefix still applies. The driver validates the hostname before every request. Applications remain responsible for trusting their connection configuration and custom fetch implementations.

License

Apache 2.0, see LICENSE.