TiDB Cloud Serverless Driver (Beta)

Why use TiDB Cloud Serverless Driver (Beta)

Traditional TCP-based MySQL drivers are not suitable for serverless functions due to their expectation of long-lived, persistent TCP connections, which contradict the short-lived nature of serverless functions. Moreover, in edge environments such as Vercel Edge Functions and Cloudflare Workers, where comprehensive TCP support and full Node.js compatibility may be lacking, these drivers may not work at all.

TiDB Cloud serverless driver (Beta) for JavaScript allows you to connect to your TiDB Serverless cluster over HTTP, which is generally supported by serverless environments. With it, it is now possible to connect to TiDB Serverless clusters from edge environments and reduce connection overhead with TCP while keeping the similar development experience of traditional TCP-based MySQL drivers.

Install the serverless driver

You can install the driver with npm:

npm install @tidbcloud/serverless

Use the serverless driver

You can use the serverless driver to query data of a TiDB Serverless cluster or perform interactive transactions.

Query

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

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])

Transaction (experimental)

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

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 examples

Here are some examples of using the serverless driver in edge environments. For a complete example, you can also try this live demo.

• Vercel Edge Function
• Cloudflare Workers
• Netlify Edge Function
• Deno
• Bun

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});
}

import { connect } from '@tidbcloud/serverless'
export interface Env {
  DATABASE_URL: string;
}
export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const conn = connect({url: env.DATABASE_URL})
    const result = await conn.execute('show tables')
    return new Response(JSON.stringify(result));
  },
};

import { connect } from 'https://esm.sh/@tidbcloud/serverless'

export default async () => {
  const conn = connect({url: Netlify.env.get('DATABASE_URL')})
  const result = await conn.execute('show tables')
  return new Response(JSON.stringify(result));
}

import { connect } from "npm:@tidbcloud/serverless-js"

const conn = connect({url: Deno.env.get('DATABASE_URL')})
const result = await conn.execute('show tables')

import { connect } from "@tidbcloud/serverless-js"

const conn = connect({url: Bun.env.DATABASE_URL})
const result = await conn.execute('show tables')

Configure the serverless driver

You can configure TiDB Cloud serverless driver at both the connection level and the SQL level.

Connection level configurations

At the connection level, you can make the following configurations:

Database URL

When url is configured, there is no need to configure host, username, password, and database separately. The following codes are equivalent:

const config = {
  host: '<host>',
  username: '<user>',
  password: '<password>',
  database: '<database>',
  arrayMode: true,
}

const conn = connect(config)

const config = {
  url: process.env['DATABASE_URL'] || 'mysql://[username]:[password]@[host]/[database]',
  arrayMode: true
}

const conn = connect(config)

SQL level options

At the SQL level, you can configure the following options:

arrayMode and fullResult

To return the full result object as arrays, you can configure the arrayMode and fullResult options as follows:

const conn = connect({url: process.env['DATABASE_URL'] || 'mysql://[username]:[password]@[host]/[database]'})
const results = await conn.execute('select * from test',null,{arrayMode:true,fullResult:true})

isolation

The isolation option can only be used in the begin function.

const conn = connect({url: 'mysql://[username]:[password]@[host]/[database]'})
const tx = await conn.begin({isolation:"READ COMMITTED"})

decoders

To customize the format of returned column values, you can configure the decoder option in the connect() method as follows:

import { connect, ColumnType } from '@tidbcloud/serverless';

const conn = connect({
  url: 'mysql://[username]:[password]@[host]/[database]',
  decoders: {
    // By default, TiDB Cloud serverless driver returns the BIGINT type as text value. This decoder converts BIGINT to the JavaScript built-in BigInt type.
    [ColumnType.BIGINT]: (rawValue: string) => BigInt(rawValue),
    
    // By default, TiDB Cloud serverless driver returns the DATETIME type as the text value in the 'yyyy-MM-dd HH:mm:ss' format. This decoder converts the DATETIME text to the JavaScript native Date object.
    [ColumnType.DATETIME]: (rawValue: string) => new Date(rawValue),
  }
})

// You can also configure the decoder option at the SQL level to override the decoders with the same keys at the connection level.
conn.execute(`select ...`, [], {
  decoders: {
    // ...
  }
})

Features

Supported SQL statements

DDL is supported and the following SQL statements are supported: SELECT, SHOW, EXPLAIN, USE, INSERT, UPDATE, DELETE, BEGIN, COMMIT, ROLLBACK, and SET.

Data type mapping

The type mapping between TiDB Serverless and Javascript is as follows:

ORM integrations

TiDB Cloud serverless driver has been integrated with the following ORMs:

• TiDB Cloud serverless driver Kysely dialect.
• TiDB Cloud serverless driver Prisma adapter.

Pricing

The serverless driver itself is free, but accessing data with the driver generates Request Units (RUs) and storage usage. The pricing follows the TiDB Serverless pricing model.

Limitations

Currently, using serverless driver has the following limitations:

• Up to 10,000 rows can be fetched in a single query.
• You can execute only a single SQL statement at a time. Multiple SQL statements in one query are not supported yet.
• Connection with private endpoints is not supported yet.

What's next

• Learn how to use TiDB Cloud serverless driver in a local Node.js project.