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サーバーレス ドライバーを使用する方法を学習します。