重要

このページは英語版のページを機械翻訳しています。原文はこちらからご覧ください。

TypeORM で TiDB に接続する

TiDB は MySQL 互換データベースであり、 TypeORMは Node.js 用の人気のあるオープンソース ORM フレームワークです。

このチュートリアルでは、TiDB と TypeORM を使用して次のタスクを実行する方法を学習できます。

環境をセットアップします。
TypeORM を使用して TiDB クラスターに接続します。
アプリケーションをビルドして実行します。オプションで、基本的な CRUD 操作のサンプルコードスニペットを見つけることができます。

注記
このチュートリアルは、TiDB サーバーレス、TiDB 専用、および TiDB セルフホストで動作します。

前提条件

このチュートリアルを完了するには、次のものが必要です。

Node.js >= 16.x がマシンにインストールされている。
ギットマシンにインストールされています。
TiDB クラスターが実行中です。

TiDB クラスターがない場合は、次のように作成できます。

(推奨) TiDB サーバーレスクラスターの作成に従って、独自のTiDB Cloudクラスターを作成します。
ローカルテスト TiDB クラスターをデプロイまたは本番TiDB クラスターをデプロイに従ってローカルクラスターを作成します。

(推奨) TiDB サーバーレスクラスターの作成に従って、独自のTiDB Cloudクラスターを作成します。
ローカルテスト TiDB クラスターをデプロイまたは本番TiDB クラスターをデプロイに従ってローカルクラスターを作成します。

サンプルアプリを実行して TiDB に接続する

このセクションでは、サンプルアプリケーションコードを実行して TiDB に接続する方法を説明します。

ステップ 1: サンプルアプリリポジトリのクローンを作成する

ターミナルウィンドウで次のコマンドを実行して、サンプルコードリポジトリのクローンを作成します。

git clone https://github.com/tidb-samples/tidb-nodejs-typeorm-quickstart.git
cd tidb-nodejs-typeorm-quickstart

ステップ 2: 依存関係をインストールする

次のコマンドを実行して、サンプルアプリに必要なパッケージ ( typeormとmysql2を含む) をインストールします。

npm install

依存関係を既存のプロジェクトにインストールする

既存のプロジェクトの場合、次のコマンドを実行してパッケージをインストールします。

typeorm : Node.js の ORM フレームワーク。
mysql2 : Node.js 用の MySQL ドライバー。 mysqlドライバーも使えます。
dotenv : .envファイルから環境変数をロードします。
typescript : TypeScript コードを JavaScript にコンパイルします。
ts-node : TypeScript コードをコンパイルせずに直接実行します。
@types/node : Node.js の TypeScript 型定義を提供します。

npm install typeorm mysql2 dotenv --save
npm install @types/node ts-node typescript --save-dev

ステップ 3: 接続情報を構成する

選択した TiDB デプロイメントオプションに応じて、TiDB クラスターに接続します。

TiDB Serverless
TiDB Dedicated
TiDB Self-Hosted

クラスターページに移動し、ターゲットクラスターの名前をクリックして、その概要ページに移動します。
右上隅にある「接続」をクリックします。接続ダイアログが表示されます。
接続ダイアログの設定が動作環境と一致していることを確認してください。
- エンドポイントタイプはPublicに設定されます。
- ブランチはmainに設定されます。
- [接続先] はGeneralに設定されます。
- [オペレーティングシステム] は、アプリケーションを実行するオペレーティングシステムと一致します。
パスワードをまだ設定していない場合は、 「パスワードの生成」をクリックしてランダムなパスワードを生成します。
次のコマンドを実行して.env.exampleをコピーし、名前を.envに変更します。
```
cp .env.example .env
```
.envファイルを編集し、次のように環境変数を設定し、接続ダイアログ上の対応するプレースホルダー{}接続パラメーターに置き換えます。
```
TIDB_HOST={host}
TIDB_PORT=4000
TIDB_USER={user}
TIDB_PASSWORD={password}
TIDB_DATABASE=test
TIDB_ENABLE_SSL=true
```
注記
TiDB サーバーレスの場合、パブリックエンドポイントを使用する場合はTIDB_ENABLE_SSL経由の TLS 接続を有効にする必要があります。
.envファイルを保存します。

クラスターページに移動し、ターゲットクラスターの名前をクリックして、その概要ページに移動します。
右上隅にある「接続」をクリックします。接続ダイアログが表示されます。
「どこからでもアクセスを許可」をクリックし、 「TiDB クラスター CA のダウンロード」をクリックして CA 証明書をダウンロードします。
接続文字列の取得方法の詳細については、 TiDB専用標準接続を参照してください。
次のコマンドを実行して.env.exampleをコピーし、名前を.envに変更します。
```
cp .env.example .env
```
.envファイルを編集し、次のように環境変数を設定し、接続ダイアログ上の対応するプレースホルダー{}接続パラメーターに置き換えます。
```
TIDB_HOST={host}
TIDB_PORT=4000
TIDB_USER={user}
TIDB_PASSWORD={password}
TIDB_DATABASE=test
TIDB_ENABLE_SSL=true
TIDB_CA_PATH={downloaded_ssl_ca_path}
```
注記
TiDB D dedicated の場合、パブリックエンドポイントを使用する場合はTIDB_ENABLE_SSL経由の TLS 接続を有効にすることが推奨されます。 TIDB_ENABLE_SSL=trueを設定する場合は、 TIDB_CA_PATH=/path/to/ca.pemを介して接続ダイアログからダウンロードした CA 証明書のパスを指定する必要があります。
.envファイルを保存します。

次のコマンドを実行して.env.exampleをコピーし、名前を.envに変更します。
```
cp .env.example .env
```
.envファイルを編集し、次のように環境変数を設定し、対応するプレースホルダー{} TiDB クラスターの接続パラメーターに置き換えます。
```
TIDB_HOST={host}
TIDB_PORT=4000
TIDB_USER=root
TIDB_PASSWORD={password}
TIDB_DATABASE=test
```
TiDB をローカルで実行している場合、デフォルトのホストアドレスは127.0.0.1で、パスワードは空です。
.envファイルを保存します。

ステップ 4: データベーススキーマを初期化する

次のコマンドを実行して TypeORM CLI を呼び出し、 src/migrationsフォルダー内の移行ファイルに書き込まれた SQL ステートメントでデータベースを初期化します。

npm run migration:run

予想される実行出力

次の SQL ステートメントはplayersテーブルとprofilesテーブルを作成し、2 つのテーブルは外部キーを介して関連付けられます。

query: SELECT VERSION() AS `version`
query: SELECT * FROM `INFORMATION_SCHEMA`.`COLUMNS` WHERE `TABLE_SCHEMA` = 'test' AND `TABLE_NAME` = 'migrations'
query: CREATE TABLE `migrations` (`id` int NOT NULL AUTO_INCREMENT, `timestamp` bigint NOT NULL, `name` varchar(255) NOT NULL, PRIMARY KEY (`id`)) ENGINE=InnoDB
query: SELECT * FROM `test`.`migrations` `migrations` ORDER BY `id` DESC
0 migrations are already loaded in the database.
1 migrations were found in the source code.
1 migrations are new migrations must be executed.
query: START TRANSACTION
query: CREATE TABLE `profiles` (`player_id` int NOT NULL, `biography` text NOT NULL, PRIMARY KEY (`player_id`)) ENGINE=InnoDB
query: CREATE TABLE `players` (`id` int NOT NULL AUTO_INCREMENT, `name` varchar(50) NOT NULL, `coins` decimal NOT NULL, `goods` int NOT NULL, `created_at` datetime NOT NULL, `profilePlayerId` int NULL, UNIQUE INDEX `uk_players_on_name` (`name`), UNIQUE INDEX `REL_b9666644b90ccc5065993425ef` (`profilePlayerId`), PRIMARY KEY (`id`)) ENGINE=InnoDB
query: ALTER TABLE `players` ADD CONSTRAINT `fk_profiles_on_player_id` FOREIGN KEY (`profilePlayerId`) REFERENCES `profiles`(`player_id`) ON DELETE NO ACTION ON UPDATE NO ACTION
query: INSERT INTO `test`.`migrations`(`timestamp`, `name`) VALUES (?, ?) -- PARAMETERS: [1693814724825,"Init1693814724825"]
Migration Init1693814724825 has been  executed successfully.
query: COMMIT

移行ファイルは、 src/entitiesフォルダーで定義されたエンティティから生成されます。 TypeORM でエンティティを定義する方法については、 TypeORM: エンティティを参照してください。

ステップ 5: コードを実行して結果を確認する

次のコマンドを実行してサンプルコードを実行します。

npm start

予想される実行出力:

接続が成功すると、ターミナルは次のように TiDB クラスターのバージョンを出力します。

🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-v7.5.1)
🆕 Created a new player with ID 2.
ℹ️ Got Player 2: Player { id: 2, coins: 100, goods: 100 }
🔢 Added 50 coins and 50 goods to player 2, now player 2 has 100 coins and 150 goods.
🚮 Deleted 1 player data.

サンプルコードスニペット

次のサンプルコードスニペットを参照して、独自のアプリケーション開発を完了できます。

完全なサンプルコードとその実行方法については、 tidb-samples/tidb-nodejs-typeorm-quickstartリポジトリを確認してください。

接続オプションを使用して接続する

次のコードは、環境変数で定義されたオプションを使用して TiDB への接続を確立します。

// src/dataSource.ts

// Load environment variables from .env file to process.env.
require('dotenv').config();

export const AppDataSource = new DataSource({
  type: "mysql",
  host: process.env.TIDB_HOST || '127.0.0.1',
  port: process.env.TIDB_PORT ? Number(process.env.TIDB_PORT) : 4000,
  username: process.env.TIDB_USER || 'root',
  password: process.env.TIDB_PASSWORD || '',
  database: process.env.TIDB_DATABASE || 'test',
  ssl: process.env.TIDB_ENABLE_SSL === 'true' ? {
    minVersion: 'TLSv1.2',
    ca: process.env.TIDB_CA_PATH ? fs.readFileSync(process.env.TIDB_CA_PATH) : undefined
  } : null,
  synchronize: process.env.NODE_ENV === 'development',
  logging: false,
  entities: [Player, Profile],
  migrations: [__dirname + "/migrations/**/*{.ts,.js}"],
});

注記
TiDB サーバーレスの場合、パブリックエンドポイントを使用する場合は TLS 接続を有効にする必要があります。このサンプルコードでは、 .envファイルの環境変数TIDB_ENABLE_SSL trueに設定してください。
ただし、Node.js はデフォルトで組み込みのMozilla CA 証明書を使用し、TiDB Serverless によって信頼されるため、 TIDB_CA_PATH経由で SSL CA 証明書を指定する必要はありません。

データの挿入

次のクエリは、単一のPlayerレコードを作成し、TiDB によって生成されたidフィールドを含む、作成されたPlayerオブジェクトを返します。

const player = new Player('Alice', 100, 100);
await this.dataSource.manager.save(player);

詳細については、データの挿入を参照してください。

クエリデータ

次のクエリは、ID 101 の単一のPlayerオブジェクトを返します。レコードが見つからない場合はnull返します。

const player: Player | null = await this.dataSource.manager.findOneBy(Player, {
  id: id
});

詳細については、クエリデータを参照してください。

データを更新する

次のクエリは、ID 101の商品Playerに商品50を追加します。

const player = await this.dataSource.manager.findOneBy(Player, {
  id: 101
});
player.goods += 50;
await this.dataSource.manager.save(player);

詳細については、データを更新するを参照してください。

データの削除

次のクエリは、ID 101のPlayer削除します。

await this.dataSource.manager.delete(Player, {
  id: 101
});

詳細については、データの削除を参照してください。

生のSQLクエリを実行する

次のクエリは、生の SQL ステートメント ( SELECT VERSION() AS tidb_version; ) を実行し、TiDB クラスターのバージョンを返します。

const rows = await dataSource.query('SELECT VERSION() AS tidb_version;');
console.log(rows[0]['tidb_version']);

詳細については、 TypeORM: データソース APIを参照してください。

便利なメモ

外部キー制約

外部キー制約 (実験的) を使用すると、データベース側でチェックを追加することでデータの参照整合性が保証されます。ただし、これにより、データ量が大きいシナリオでは、パフォーマンスに重大な問題が発生する可能性があります。

createForeignKeyConstraintsオプション (デフォルト値はtrue ) を使用して、エンティティ間の関係を構築するときに外部キー制約を作成するかどうかを制御できます。

@Entity()
export class ActionLog {
    @PrimaryColumn()
    id: number

    @ManyToOne((type) => Person, {
        createForeignKeyConstraints: false,
    })
    person: Person
}

詳細については、 TypeORMFAQおよび外部キー制約を参照してください。

次のステップ

TypeORM の詳しい使い方はTypeORM のドキュメントからご覧ください。
開発者ガイドの章 ( データの挿入など) で TiDB トランザクション SQLパフォーマンスの最適化データを更新するベストプラクティスクエリデータ学習データの削除ます。
プロフェッショナルとしてTiDB 開発者コースを学び、試験合格後にTiDB 認定獲得します。

助けが必要？

不和またはサポートチケットを作成するについて質問してください。