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 に接続する方法を説明します。

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

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

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

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

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

npm install

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

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

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

npm run migration:run

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: 5.7.25-TiDB-v7.1.3)
🆕 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 認定獲得します。

助けが必要？

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