JS Date & Timezone Guide

Store a Date-Only Value in a Database with Temporal

To store a date with no time or zone, use a DATE column and Temporal.PlainDate.toString() so the value can never shift across timezones. Part of Serializing and Storing Temporal Values.

Why this scenario is tricky

A date-only value — a birthday, an invoice date, a holiday — has no time and no zone. Store it in a timestamptz column and the database attaches midnight in some zone; read it back in another zone and it can shift to the previous day. The whole class of off-by-one bugs comes from letting a zone touch a value that should never have had one.

Keep civil dates out of timestamp columnsA timestamptz shifts a bare date across zonesKeep civil dates out of timestamp columnsDATE stored as timestamptzmidnight+zone → off by oneDATE column + PlainDateno zone ever appliedUse a DATE column so a birthday is the same day for everyone.

Minimal working solution

import { Temporal } from '@js-temporal/polyfill';
const dob = Temporal.PlainDate.from('1990-02-14');
const value = dob.toString();      // '1990-02-14' → store in a DATE column
const back = Temporal.PlainDate.from(value); // exact same civil date

Civil date, DATE columnPlainDate.toString maps straight to a DATECivil date, DATE columnPlainDatetoString()→ DATE colfrom() back

Full production version

Guard the boundary so a Date or ZonedDateTime can never sneak into the date-only field.

import { Temporal } from '@js-temporal/polyfill';
function toDateColumn(v: Temporal.PlainDate | string): string {
  const d = typeof v === 'string' ? Temporal.PlainDate.from(v) : v;
  return d.toString(); // always 'YYYY-MM-DD', never a time or zone
}

Boundary guardCoerce to PlainDate before writingBoundary guardinputto PlainDatetoStringDATE col

Verification snippet

Date-only storage assertionsThe value never shifts across zonesAssertions that prove the edge casewrite '1990-02-14'reads '1990-02-14'in UTCsamein Pacific/Kiritimatisameno time addedtrue

Common pitfalls

Date-only pitfallsTimestamp columns and Date coercionWrongRightstore in timestamptzoff-by-one on readDATE column + PlainDatezone-freenew Date('1990-02-14')UTC midnight instantPlainDate.fromcivil, exact

Frequently Asked Questions

Why does a stored birthday show the wrong day for some users?

It was stored in a timestamp-with-zone column, which attaches midnight in one zone; read in another zone that midnight moves to the previous or next day. Store date-only values in a DATE column using Temporal.PlainDate so no zone is ever applied.

Should I use timestamptz for an invoice date?

No. An invoice date is a civil date with no time, so timestamptz only adds ambiguity. A DATE column holding PlainDate.toString() keeps it exact and identical for every reader regardless of their zone.