概要

Drizzle ORMの「Insert」クエリは、データベースに新しいデータを追加するためのメソッドです。単一レコードや複数レコードの挿入、挿入後のデータの取得など、柔軟なデータ追加が可能です。特に、TypeScriptの型安全性と連携しながらデータベース操作ができるため、効率的かつ信頼性の高いデータ挿入が実現します。本記事では、Drizzle ORMでのInsertクエリの基本的な使い方から、複数レコードの挿入方法、挿入後の戻り値取得について詳しく解説します。

Drizzle ORMのInsertクエリとは

Drizzle ORMにおけるInsertクエリは、データベーステーブルに新しいレコードを追加するための機能です。insertメソッドとvaluesメソッドを使い、挿入するデータを指定します。また、挿入時に戻り値を取得するreturningメソッドを組み合わせることで、挿入したレコードの情報を利用した後続の操作が可能です。

主な特徴

  1. 型安全なデータ挿入
    TypeScriptと統合されており、挿入データの型が保証されます。
  2. 単一・複数レコードの挿入
    単一レコードだけでなく、複数レコードを一度に挿入することも可能です。
  3. 挿入後のデータ取得
    挿入操作後に、挿入されたデータの戻り値を取得できるため、追加したレコードの確認やさらなる操作が容易です。

Insertクエリの基本的な使用方法

Drizzle ORMのInsertクエリは、insertメソッドとvaluesメソッドを使って実行します。以下に、基本的なInsertクエリの例を示します。

単一レコードの挿入

単一レコードを挿入するには、insertメソッドでテーブルを指定し、valuesメソッドでデータを渡します。以下は、usersテーブルにユーザーを1人追加する例です。

import { users } from './path/to/schemaDefinitions';
async function addUser() {
    await db.insert(users).values({
        name: 'Alice',
        email: 'alice@example.com',
        age: 30,
    });
    console.log('User added successfully');
}

挿入後のデータを取得（Returning）

挿入後にデータの確認を行いたい場合、returningメソッドを使用すると、追加したデータの戻り値を取得できます。

async function addUserWithReturn() {
    const result = await db.insert(users).values({
        name: 'Bob',
        email: 'bob@example.com',
        age: 25,
    }).returning();
    console.log('Inserted user:', result);
}

この例では、挿入されたデータがresultに格納され、ログに表示されます。

複数レコードの一括挿入

複数のレコードを一度に挿入する場合、valuesメソッドにデータの配列を渡します。これにより、効率的に複数レコードを追加でき、処理時間が短縮されます。

async function addMultipleUsers() {
    await db.insert(users).values([
        { name: 'Charlie', email: 'charlie@example.com', age: 28 },
        { name: 'Diana', email: 'diana@example.com', age: 32 },
    ]);
    console.log('Multiple users added successfully');
}

この例では、usersテーブルにCharlieとDianaのデータが一度に追加されます。

高度なInsertクエリの使用方法

Drizzle ORMのInsertクエリは、データの追加以外にもさまざまなオプションを提供しています。以下に、特定の要件に合わせた挿入方法をいくつか紹介します。

条件付き挿入（Conflict）

データベースの一意制約に基づき、既存のレコードがある場合に処理を分岐させる「Conflict」オプションを利用できます。この例では、emailが一意であると仮定し、既に存在する場合は更新操作に切り替える設定です。

async function addUserWithConflictResolution() {
    await db.insert(users).values({
        name: 'Eve',
        email: 'eve@example.com',
        age: 27,
    }).onConflictDoUpdate({
        target: users.email,
        set: { age: 27 },
    });
    console.log('User added or updated successfully');
}

このクエリにより、emailが既に存在する場合はageカラムのみが更新され、存在しない場合は新しいレコードが挿入されます。

サブクエリを使った挿入

サブクエリを利用して、他のテーブルから取得したデータを使って挿入を行うこともできます。例えば、adminsテーブルのデータを基にusersテーブルにデータを追加する例です。

import { admins } from './path/to/schemaDefinitions';
async function addUserFromAdminData() {
    const adminData = await db.select(admins.name, admins.email).from(admins).where(admins.role.eq('admin'));
    
    await db.insert(users).values(adminData);
    console.log('Users added from admin data');
}

この方法では、サブクエリから取得したデータをusersテーブルに追加できます。

Drizzle ORM Insertクエリの活用シーン

Drizzle ORMのInsertクエリは、さまざまな場面で効率的なデータ追加が可能です。

  • ユーザー登録機能
    新規ユーザーの登録時に、ユーザー情報をデータベースに追加する場面で便利です。
  • 大量データの一括登録
    テストデータや初期データを複数レコードで一括挿入することで、環境構築が効率化されます。
  • 競合解決を伴うデータ更新
    既存データと衝突する場合、競合解決オプションを使うことで、データの重複を避けながら更新できます。

注意点

  • データ型の整合性
    挿入データが正しい型であるか事前に確認することが重要です。型が不一致の場合、エラーが発生します。
  • 競合解決の設定
    onConflictDoUpdateを使用する場合、対象カラムが一意制約を持っていることを確認してください。でないと、エラーが発生する可能性があります。
  • パフォーマンス最適化
    大量データを挿入する際、挿入速度が問題になることがあります。必要に応じてトランザクションを使用し、複数の挿入操作をまとめるとパフォーマンスが向上します。

まとめ

Drizzle ORMのInsert クエリは、データベースへのデータ追加を効率的に行うための強力なツールです。単一レコードから複数レコード、競合解決付きの挿入など、多様なデータ挿入方法をサポートしており、さまざまな開発ニーズに応えられます。型安全なクエリビルダーとしての特長を活かし、Drizzle ORMのInsertクエリを活用して、効率的で安全なデータ管理を実現しましょう。

参照:

Insertクエリ - `Drizzle` ORM Documentation