Skip to content
VibORM
Esc
↑↓navigate↵open⌘Jpreview
On this page

DateTime

DateTime, date, and time scalar types for timestamps with auto-timestamp helpers

Basic Usage

import { s } from "viborm";

s.dateTime()               // Required timestamp (Date)
s.dateTime().nullable()    // Date | null
s.date()                   // Calendar date, no time component (Date)
s.time()                   // Time of day, no date component (string)

All three support the full modifier reference. Column types and precision options live on Native Types.

Auto-Timestamps

s.dateTime().now()        // Default to current timestamp on create
s.dateTime().updatedAt()  // Current timestamp on create and omitted update input

.now() and .updatedAt() also exist on s.date() and s.time().

Creation timestamps are insert-only

A .now() field is set when the row is created — from the value you pass, or the current time when you pass none — and is never assigned by an update. update, updateMany, the update arm of upsert, and every nested update refuse the key: TypeScript rejects it (also in a payload held in a variable), and at runtime the call fails with Unknown key: createdAt before the forbidden assignment executes — including { set: ... } and an explicit undefined. A root update issues no statement at all; a nested update is refused at its own admission, after the work that preceded it in the same operation, with the existing transaction and progress semantics. An explicit createdAt: undefined is the one spelling TypeScript cannot reject, because an optional key always admits undefined: it compiles, and the runtime refuses it.

The generator declared last decides: .now().updatedAt() is an updatedAt field and stays updatable, .updatedAt().now() is a creation timestamp. Modifiers that keep the generator keep the restriction, so .now().default(value) and .nullable().now() are insert-only too, while a plain .default(value) is not. This restricts what the typed client writes; it does not stop raw SQL, other writers or database cascades from changing the column.

Update timestamps

For non-array DateTime, Date and Time fields, .updatedAt() supplies the current value when an update payload omits the field or sets it to undefined. This applies to update, updateMany, the update arm of upsert, and nested updates. An explicit data: {} also refreshes it; it is not a no-op on a model with an automatic update timestamp. An update matching no rows still changes no rows.

A valid explicit value wins, including { set: value }. Create behavior is unchanged: an explicit create value wins over its default. .updatedAt().default(value) overrides the create default, not the clock used for omitted updates. An ordinary .default(value) does not make a field refresh on update.

The clock is the application’s wall clock at input admission, not the database’s statement or commit time. DateTime uses the UTC instant, Date its UTC calendar date, and Time its UTC time of day to whole seconds. This is not a monotonic counter: two updates may receive the same value.

The value is evaluated once per admitted field occurrence. A scalar bulk update shares its admitted value across the affected rows. A relation-bearing series admits its members separately, so their values may differ. Reusing already-admitted input during a permitted retry does not read the clock again; any newly admitted occurrence uses its own admission time. Transaction ownership, failure timing and partial-progress rules are unchanged. Raw SQL, database cascades and external writers do not run this client-side generator.

Temporal arrays accept explicit array values and defaults. Omission leaves the array unchanged. A scalar .now() or .updatedAt() generator cannot produce an array, so combining either with .array() is refused at declaration in both modifier orders.

Timezones

s.dateTime() defaults to a timezone-aware PostgreSQL timestamp. Chain .withoutTimezone() for a timestamp without a timezone. s.time() defaults to TIME without a timezone because its logical value is a time of day, without an offset. Both default to millisecond storage precision.

s.dateTime().withoutTimezone()  // timestamp instead of timestamptz
s.time()                       // time without a timezone

Input Types

DateTime scalars accept both Date objects and ISO strings:

// Both are valid in queries
await client.user.create({
  data: {
    createdAt: new Date(),           // Date object
    updatedAt: "2024-01-15T10:30:00Z" // ISO string
  }
});

On SQLite-family drivers, text written outside the typed client in a spelling other than the canonical YYYY-MM-DDTHH:mm:ss.sssZ / HH:mm:ss.sss compares wrongly; viborm check --db finds it, and repairing foreign timestamp and Time text rewrites it.

Examples

// Created timestamp (set once, refused by updates)
const createdAt = s.dateTime().now();

// Updated timestamp (auto-updates)
const updatedAt = s.dateTime().updatedAt();

// Optional date
const lastLogin = s.dateTime().nullable();

// Birthday - no time component needed
const birthday = s.date().nullable();

// Opening hours
const opensAt = s.time();

Common Patterns

Timestamps on All Models

const timestamps = {
  createdAt: s.dateTime().now(),
  updatedAt: s.dateTime().updatedAt(),
};

const user = s.model({
  id: s.string().id().ulid(),
  email: s.string(),
  ...timestamps,
});

const post = s.model({
  id: s.string().id().ulid(),
  title: s.string(),
  ...timestamps,
});

For the soft-delete pattern (deleted flag + deletedAt timestamp), see Boolean.

Scheduled Publishing

const post = s.model({
  id: s.string().id().ulid(),
  title: s.string(),
  publishAt: s.dateTime().nullable(),
  publishedAt: s.dateTime().nullable(),
});

// Find scheduled posts ready to publish
await client.post.findMany({
  where: {
    publishAt: { lte: new Date() },
    publishedAt: null,
  },
});

Was this page helpful?