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

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

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

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

注記：

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

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

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

npm install @tidbcloud/serverless

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

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

クエリ

TiDB Cloud Serverless クラスターからデータをクエリするには、まず接続を作成する必要があります。次に、接続を使用して生の 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
}

エッジの例

エッジ環境でサーバーレス ドライバーを使用する例をいくつか示します。完全な例については、こちらライブデモも試してください。

• Vercel Edge Function
• Cloudflare Workers
• Netlify Edge Function
• Deno
• Bun

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 がサポートされDELETE UPDATE 、次のSETステートメントEXPLAINサポートされSHOW USE INSERT COMMIT SELECT BEGINおよびROLLBACK 。

データ型マッピング

TiDB Cloud Serverless と 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 Serverless の価格モデルに従います。

制限事項

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

• 1 回のクエリで最大 10,000 行を取得できます。
• 一度に実行できる SQL ステートメントは 1 つだけです。1 つのクエリで複数の SQL ステートメントを実行することはまだサポートされていません。
• プライベートエンドポイントとの接続はまだサポートされていません。

次は何か

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