SQLの日付・タイムスタンプカラムをPrismaのDateTimeに変換する

日付と時刻のマッピング

SQLデータベースは、異なる精度とタイムゾーン対応を持つ複数の時間型を提供しています。Prismaは単一のDateTimeスカラー型を使用し、ネイティブアノテーションで基になるデータベース型を保持します。

SQLの例

CREATE TABLE events (
  id SERIAL PRIMARY KEY,
  title VARCHAR(255) NOT NULL,
  event_date DATE NOT NULL,
  starts_at TIMESTAMP NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

生成されるPrismaスキーマ

model Event {
  id        Int      @id @default(autoincrement())
  title     String
  eventDate DateTime @db.Date
  startsAt  DateTime @db.Timestamp()
  createdAt DateTime @default(now()) @db.Timestamptz()
  updatedAt DateTime @updatedAt @db.Timestamptz()

  @@map("events")
}

型マッピング表

SQL型	Prisma型	ネイティブアノテーション
DATE	DateTime	@db.Date
TIME	DateTime	@db.Time()
TIMESTAMP	DateTime	@db.Timestamp()
TIMESTAMPTZ	DateTime	@db.Timestamptz()
DATETIME（MySQL）	DateTime	@db.DateTime()

@updatedAt属性

Prismaは特別な@updatedAt属性を提供しており、Prismaクライアント経由でレコードが更新されるたびに自動的にフィールドを現在のタイムスタンプに設定します。コンバーターはupdated_at、modified_at、last_modifiedという名前のカラムを検出し、この属性を適用します。

@updatedAtはPrismaクライアントレベルで機能し、データベースレベルではないことに注意してください。直接SQLで更新する場合にもデータベースレベルの自動更新が必要な場合は、SQLトリガーも維持してください。

NOW()とデフォルト

SQLのDEFAULT NOW()、DEFAULT CURRENT_TIMESTAMP、DEFAULT GETDATE()はすべてPrismaの@default(now())にマッピングされます。これにより、レコード作成時に値が設定されます。

タイムゾーンのベストプラクティス

PostgreSQLでは常にTIMESTAMPよりTIMESTAMPTZを優先してください。コンバーターは@db.Timestamptz()と@db.Timestamp()でこの区別を保持します。MySQLでは、同等のものはDATETIME（タイムゾーンなし）とTIMESTAMP（自動的にUTCに変換）です。

精度

一部のデータベースは小数秒の精度をサポートしています：

created_at TIMESTAMP(6) WITH TIME ZONE

Prismaでは@db.Timestamptz(6)にマッピングされ、マイクロ秒精度が保持されます。

日付のみのフィールド

時間コンポーネントのないカレンダー日付を表すフィールドには@db.Dateを使用してください — 誕生日、締切日、イベント日など。日付のみが重要な場合のタイムゾーンの混乱を避けることができます。