@shiyuhang0/serverless-js

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

Usage

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)

Connection factory

Use the Client connection factory class to create fresh connections for each transaction or web request handler.

const client = new Client({
  host: '<host>',
  username: '<user>',
  password: '<password>'
})

const conn = client.connection()
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. If any unhandled errors are thrown during execution of the transaction, the transaction will be rolled back.

import { connect } from '@planetscale/database'

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

const conn = connect(config)
const results = await conn.transaction(async (tx) => {
  const result1 = await tx.execute('INSERT INTO table1 (id, name) VALUES (?, ?)', [1, "test"])
  const result2 = await tx.execute('INSERT INTO table2 (id, name) VALUES (?, ?)', [1, "test"])
  return [result1, result2]
})
console.log(results)

Configuration

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'
}

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 '@planetscale/database'
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 dual')
console.log(results)