TiDB CloudサーバーレスDriver(ベータ版)

注記：

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

TiDB Cloud Serverless Driver (ベータ版) を使用する理由

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

JavaScript版のTiDB Cloudサーバーレス ドライバー (ベータ版)使用すると、サーバーレス環境で一般的にサポートされている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"})

デコーダー

返される列の値の形式をカスタマイズするには、 connect()メソッドのdecoderオプションを次のように構成します。

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サーバーレス ドライバーは UTF-8 エンコードを使用して JavaScript 文字列を文字列にデコードするため、JavaScript 文字列への型変換には必ずTiDB Cloudのデフォルトのutf8mb4文字セットを使用してください。

注記：

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

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

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文を実行することはまだサポートされていません。
• プライベートエンドポイントとの接続はまだサポートされていません。

次は何？

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