TiDB Cloud Serverless Driver for JavaScript

A Fetch API-compatible TiDB Cloud database driver based on planetscale-serverless-driver. Thanks for their great work!

User Guide

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

Installation

npm install @shiyuhang0/serverless

Usage

import { connect } from '@shiyuhang0/serverless'

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

const conn = connect(config)
const results = await conn.execute('select 1 from sample_data.github_events')
console.log(results)

Transactions

Use the transaction function to safely perform database transactions.

Use different client ip to execute transaction may lead to error.

import { connect } from '@shiyuhang0/serverless'

const conn = connect(config)
const tx = await conn.begin()
await tx.execute('insert into test.test values (6,"test6")')
console.log(await tx.execute('select * from test.test'))
console.log(await conn.execute('select * from test.test'))
await tx.commit()
console.log(await conn.execute('select * from test.test'))

Configuration

The following configurations are supported in connection level:

• username
• password
• host
• url
• fetch

Database URL

A single database URL value can be used to configure the host, username, and password values.

const config = {
  url: process.env['DATABASE_URL'] || 'mysql://user:pass@host/dbname'
}

const conn = connect(config)

Custom fetch function

Node.js version 18 includes a built-in global fetch function. When using an older version of Node.js, you can provide a custom fetch function implementation. We recommend the undici package on which Node's built-in fetch is based.

import { connect } from '@shiyuhang0/serverless'
import { fetch } from 'undici'

const config = {
  fetch,
  host: '<host>',
  username: '<user>',
  password: '<password>'
}

const conn = connect(config)
const results = await conn.execute('select 1 from sample_data.github_events')
console.log(results)

Options

The following options are supported in SQL level:

• arrayMode boolean (default false): whether to return results as arrays instead of objects.
• fullResult boolean (default false): whether to return full result object instead of just rows.