---
title: DateTime
description: DateTime, date, and time scalar types for timestamps with auto-timestamp helpers
icon: calendar
---

## Basic Usage

```ts
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](/docs/schema/scalars). Column types and precision options live on [Native Types](/docs/schema/native-types).

## Auto-Timestamps

```ts
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.

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

## Input Types

DateTime scalars accept both `Date` objects and ISO strings:

```ts
// 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](/docs/migration/drivers/sqlite#repairing-foreign-timestamp-and-time-text)
rewrites it.

## Examples

```ts
// 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

```ts
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](/docs/schema/scalars/boolean#soft-delete).

### Scheduled Publishing

```ts
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,
  },
});
```
