TypeORMを使用してTiDBに接続する

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

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

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

前提条件

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

• お使いのコンピューターにNode.js >= 16.xがインストールされていること。
• お使いのマシンにGitがインストールされています。
• TiDBクラスタが稼働中です。

TiDBクラスタをお持ちでない場合は、以下の手順で作成できます。

• (推奨) TiDB Cloud Starterインスタンスを作成する。
• ローカルテスト用のTiDB Self-Managedクラスタをデプロイまたは本番のTiDB Self-Managedクラスタをデプロイ

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に接続してください。

ステップ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: 8.0.11-TiDB-v8.5.4)
🆕 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}"],
});

データを挿入する

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

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
});

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

データの更新

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

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
}

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

次のステップ

• TypeORM の使用法の詳細についてはTypeORMのドキュメントを参照してください。
• 開発者ガイドのデータを挿入する、データの更新、データを削除する、クエリデータ、トランザクション、SQLパフォーマンス最適化などの章を読んで、TiDB アプリケーション開発のベストプラクティスを学びましょう。
• プロフェッショナルなTiDB開発者向けコースコースを通じて学習し、試験に合格するとTiDB認定資格を取得します。

お困りですか？

• Discordor Slackコミュニティに質問してください。
• TiDB Cloudのサポートチケットを送信してください
• TiDB Self-Managedのサポートチケットを送信してください