TiDB CloudサーバーレスDriver（ベータ版）

注記：

サーバーレスドライバーはベータ版であり、 TiDB Cloud StarterまたはTiDB Cloud Essentialインスタンスにのみ適用可能です。

TiDB Cloud Serverless Driver （ベータ版）を使用する理由

従来のTCPベースのMySQLドライバは、サーバーレス関数の短命な性質と矛盾する、長期間持続するTCP接続を前提としているため、サーバーレス関数には適していません。さらに、 Vercel Edgeの機能やCloudflare Workersなどのエッジ環境では、包括的なTCPサポートと完全なNode.js互換性が欠けている場合があり、これらのドライバは全く動作しない可能性があります。

TiDB Cloudサーバーレスドライバー（ベータ版） for JavaScript を使用すると、サーバーレス環境で一般的にサポートされている HTTP 経由でTiDB Cloud StarterまたはTiDB Cloud Essentialインスタンスに接続できます。これにより、エッジ環境からTiDB Cloud StarterまたはTiDB Cloud Essentialインスタンスに接続し、従来の TCP ベースの MySQL ドライバーと同様の開発エクスペリエンスを維持しながら、TCP による接続オーバーヘッドを削減することが可能になります。

注記：

SQL や ORM ではなく RESTful API を使用したプログラミングを好む場合は、 データサービス（ベータ版）を使用できます。

サーバーレスドライバーをインストールします

npmを使ってドライバーをインストールできます。

npm install @tidbcloud/serverless

サーバーレスドライバーを使用する

サーバーレスドライバーを使用すると、 TiDB Cloud StarterまたはTiDB Cloud Essentialインスタンスのデータを照会したり、対話型トランザクションを実行したりできます。

クエリ

TiDB Cloud StarterまたはTiDB Cloud Essentialインスタンスからデータをクエリするには、まず接続を作成する必要があります。その後、その接続を使用して生のSQLクエリを実行できます。例：

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

トランザクション（実験的）

サーバーレスドライバーを使用して対話型トランザクションを実行することもできます。例：

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
}

エッジの例

エッジ環境でサーバーレスドライバーを使用する例をいくつかご紹介します。より詳しい例については、こちらのライブデモもご覧ください。

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"

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

import { connect } from "@tidbcloud/serverless"

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

サーバーレスドライバーを設定する

TiDB Cloudのサーバーレスドライバーは、接続レベルとSQLレベルの両方で設定できます。

接続レベル構成

接続レベルでは、以下の設定を行うことができます。

データベースURL

注記：

ユーザー名、パスワード、またはデータベース名に特殊文字が含まれている場合は、URL で渡す際にこれらの文字パーセンテージエンコード必要があります。たとえば、パスワードpassword1@//? URL ではpassword1%40%2F%2F%3Fのようにエンコードする必要があります。

urlが設定されている場合、 host 、 username 、 password 、およびdatabase個別に設定する必要はありません。以下のコードは同等です。

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レベルのオプション

注記：

SQLレベルのオプションは、接続レベルの設定よりも優先順位が高くなります。

SQLレベルでは、以下のオプションを設定できます。

arrayMode と fullResult

結果オブジェクト全体を配列として返すには、 arrayModeおよびfullResultオプションを次のように設定します。

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オプションは、 begin関数でのみ使用できます。

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

デコーダー

返される列値のフォーマットをカスタマイズするには、 decoderメソッドのconnect()オプションを次のように設定します。

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: {
    // ...
  }
})

注記：

TiDB Cloudサーバーレスドライバの設定変更点：

• v0.0.7: SQL レベル オプションisolationを追加します。
• v0.0.10: 接続レベル構成decodersと SQL レベルオプションdecodersを追加します。

特徴

サポートされているSQLステートメント

DDL がサポートされており、次の SQL ステートメントがサポートされています: SELECT 、 SHOW 、 EXPLAIN 、 USE 、 INSERT 、 UPDATE 、 DELETE 、 BEGIN 、 COMMIT 、 ROLLBACK 、およびSET 。

データ型マッピング

TiDBとJavaScript間の型マッピングは以下のとおりです。

注記：

TiDB Cloud TiDB Cloudのデフォルトのutf8mb4 E}} 文字セットを使用するようにしてください。

注記：

TiDB Cloudサーバーレスドライバーのデータ型マッピングの変更点：

• v0.1.0: BINARY 、 VARBINARY 、 TINYBLOB 、 BLOB 、 MEDIUMBLOB 、 LONGBLOB 、およびBIT型は、 Uint8Arrayではなく、 string }として返されるようになりました。

ORM連携

TiDB Cloudのサーバーレスドライバーは、以下のORMと統合されています。

• TiDB Cloudサーバーレスドライバー Kysely 方言。
• TiDB Cloudサーバーレス ドライバー Prisma アダプター。

価格設定

サーバーレスドライバー自体は無料ですが、ドライバーを使用してデータにアクセスすると要求単位（RU）とstorageの使用量が発生します。

• TiDB Cloud Starterインスタンスの料金は、 TiDB Cloud Starter の価格モデルに従います。
• TiDB Cloud Essentialインスタンスの場合、価格はTiDB Cloud Essential の価格設定モデルに従います。

制限事項

現在、サーバーレスドライバーの使用には以下の制限があります。

• 1回のクエリで最大10,000行まで取得できます。
• 一度に実行できるSQL文は1つだけです。1つのクエリで複数のSQL文を実行することは、現時点ではサポートされていません。
• プライベートエンドポイントとの接続にはまだ対応していません。
• サーバーは、クロスオリジンリソース共有（CORS）を介して、許可されていないブラウザからのリクエストをブロックし、認証情報を保護します。そのため、サーバーレスドライバーはバックエンドサービスからのみ使用できます。

次は？

• ローカルのNode.jsプロジェクトでTiDB Cloudサーバーレスドライバーを使用する方法を学びましょう。