fix(sql): convert MySQL zero dates and early years

migrateScheduleDates() converted some legacy dates to wrong instants,
and a migration only runs once:

- MySQL in non-strict mode stores the zero date, 0000-00-00 00:00:00,
  for a date it cannot store. It was read as 1899-11-29, and the Knex
  MySQL created_at, read through UNIX_TIMESTAMP(), as 1970-01-01.
- Date.UTC() reads the years 0 to 99 as 1900 to 1999, so a date in the
  year 0050 became 1950. The time zone offset went through it too, and
  read the year 0 as 1, since Intl counts it as 1 BC.
- Date.UTC() moves an impossible date, such as 2026-02-31, to a later
  day, and MySQL can store one in non-strict mode.

The zero date now converts to no date; a zero created_at reaches the
error for an empty created_at, since the migrated column is required.
Wall-clock times are computed with setUTCFullYear(), which keeps every
year, and the offset reads the era for the years before 1 AD. An
impossible date or time fails the migration with the conversion error,
before the first schema change.

Author: RomainLanz

src/services/knex_queue_schema.ts

@@ -469,9 +469,14 @@ export class KnexQueueSchemaService {
 
     if (dialect === 'mysql') {
       // created_at was generated by the MySQL server in the session time zone,
-      // so the server converts it exactly.
+      // so the server converts it exactly. UNIX_TIMESTAMP() returns 0 for the
+      // zero date, which is no date.
       if (name === 'created_at') {
-        return this.#connection.raw('ROUND(UNIX_TIMESTAMP(??) * 1000) as ??', [name, name])
+        return this.#connection.raw(
+          "case when CAST(?? AS CHAR) = '0000-00-00 00:00:00' then null " +
+            'else ROUND(UNIX_TIMESTAMP(??) * 1000) end as ??',
+          [name, name, name]
+        )
       }
       return this.#connection.raw('CAST(?? AS CHAR) as ??', [name, name])
     }

src/services/schedule_dates.ts

@@ -78,6 +78,8 @@ const WALL_CLOCK = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(?:\.(\d{
  * - Digits only: already epoch milliseconds.
  * - A date with `Z` or an offset: an exact instant.
  * - A date without a time zone: a wall-clock time in `wallClockTimeZone`.
+ * - The MySQL zero date, which non-strict mode stores for a date it cannot
+ *   store: no date.
  */
 export function legacyScheduleDateToEpoch(
   value: string | number | null | undefined,
@@ -92,11 +94,16 @@ export function legacyScheduleDateToEpoch(
   const wallClock = WALL_CLOCK.exec(text)
   if (wallClock) {
     const [, year, month, day, hour, minute, second, fraction = '0'] = wallClock
-    return wallClockToEpoch(
-      [year, month, day, hour, minute, second].map(Number) as WallClockParts,
-      Math.round(Number(`0.${fraction}`) * 1000),
-      wallClockTimeZone
-    )
+    const parts = [year, month, day, hour, minute, second].map(Number) as WallClockParts
+
+    if (parts.every((part) => part === 0) && Number(fraction) === 0) return null
+
+    // Date.UTC() moves an impossible date, such as February 31, to a later one.
+    if (!isWallClock(parts)) {
+      throw new Error(`Cannot convert the schedule date "${value}" to epoch milliseconds`)
+    }
+
+    return wallClockToEpoch(parts, Math.round(Number(`0.${fraction}`) * 1000), wallClockTimeZone)
   }
 
   // PostgreSQL prints offsets as `+00` or `+05:30`; normalize to `+00:00`.
@@ -155,8 +162,7 @@ type WallClockParts = [
  * change, which moves it forward by the size of the gap.
  */
 function wallClockToEpoch(parts: WallClockParts, milliseconds: number, timeZone: string): number {
-  const [year, month, day, hour, minute, second] = parts
-  const asUtc = Date.UTC(year, month - 1, day, hour, minute, second, milliseconds)
+  const asUtc = utcEpoch(parts, milliseconds)
   const DAY = 24 * 60 * 60 * 1000
 
   // The offsets in effect a day before and a day after cover any DST change.
@@ -175,6 +181,7 @@ function timeZoneOffset(epoch: number, timeZone: string): number {
   const parts = new Intl.DateTimeFormat('en-US', {
     timeZone,
     hourCycle: 'h23',
+    era: 'short',
     year: 'numeric',
     month: '2-digit',
     day: '2-digit',
@@ -184,19 +191,44 @@ function timeZoneOffset(epoch: number, timeZone: string): number {
   }).formatToParts(new Date(epoch))
 
   const value = (type: string) => Number(parts.find((part) => part.type === type)!.value)
-  const wallClockAsUtc = Date.UTC(
-    value('year'),
-    value('month') - 1,
-    value('day'),
-    value('hour'),
-    value('minute'),
-    value('second'),
+  // Intl counts years before 1 AD from 1 BC; the year 0 is 1 BC.
+  const era = parts.find((part) => part.type === 'era')!.value
+  const year = era === 'BC' ? 1 - value('year') : value('year')
+  const wallClockAsUtc = utcEpoch(
+    [year, value('month'), value('day'), value('hour'), value('minute'), value('second')],
     new Date(epoch).getUTCMilliseconds()
   )
 
   return wallClockAsUtc - epoch
 }
 
+/**
+ * Epoch milliseconds of a wall-clock time read as UTC. Unlike Date.UTC(), it
+ * keeps the years 0 to 99 instead of reading them as 1900 to 1999.
+ */
+function utcEpoch(parts: WallClockParts, milliseconds: number): number {
+  const [year, month, day, hour, minute, second] = parts
+  const date = new Date(0)
+  date.setUTCFullYear(year, month - 1, day)
+  date.setUTCHours(hour, minute, second, milliseconds)
+  return date.getTime()
+}
+
+/** Whether the parts name a time that exists, as UTC: no month 13 or February 31. */
+function isWallClock(parts: WallClockParts): boolean {
+  const date = new Date(utcEpoch(parts, 0))
+  const [year, month, day, hour, minute, second] = parts
+
+  return (
+    date.getUTCFullYear() === year &&
+    date.getUTCMonth() === month - 1 &&
+    date.getUTCDate() === day &&
+    date.getUTCHours() === hour &&
+    date.getUTCMinutes() === minute &&
+    date.getUTCSeconds() === second
+  )
+}
+
 /** Time zone of the current process. */
 export function processTimeZone(): string {
   return Intl.DateTimeFormat().resolvedOptions().timeZone

tests/schedule_dates.spec.ts

@@ -56,6 +56,38 @@ test.group('legacyScheduleDateToEpoch', () => {
     assert.isNull(legacyScheduleDateToEpoch('', 'UTC'))
     assert.throws(() => legacyScheduleDateToEpoch('not a date', 'UTC'), /Cannot convert/)
   })
+
+  test('reads the MySQL zero date as no date', ({ assert }) => {
+    assert.isNull(legacyScheduleDateToEpoch('0000-00-00 00:00:00', 'Europe/Paris'))
+    assert.isNull(legacyScheduleDateToEpoch('0000-00-00 00:00:00.000000', 'UTC'))
+  })
+
+  test('keeps the years 0 to 99', ({ assert }) => {
+    for (const year of ['0000', '0050']) {
+      assert.equal(
+        toIso(legacyScheduleDateToEpoch(`${year}-06-01 12:00:00`, 'UTC')),
+        `${year}-06-01T12:00:00.000Z`
+      )
+      // Paris used a local mean time offset of +00:09:21 then.
+      assert.equal(
+        toIso(legacyScheduleDateToEpoch(`${year}-06-01 12:00:00`, 'Europe/Paris')),
+        `${year}-06-01T11:50:39.000Z`
+      )
+    }
+  })
+
+  test('rejects a date or time that does not exist', ({ assert }) => {
+    for (const value of [
+      '2026-02-31 00:00:00',
+      '2026-00-10 00:00:00',
+      '2026-13-01 00:00:00',
+      '2026-01-00 00:00:00',
+      '2026-01-01 24:00:00',
+      '2026-01-01 00:60:00',
+    ]) {
+      assert.throws(() => legacyScheduleDateToEpoch(value, 'UTC'), /Cannot convert/, value)
+    }
+  })
 })
 
 test.group('legacyScheduleRowToEpochs', () => {
@@ -73,11 +105,13 @@ test.group('legacyScheduleRowToEpochs', () => {
   })
 
   test('rejects a row without created_at, which the migrated table requires', ({ assert }) => {
-    const row = { id: 'no-created-at', next_run_at: null, created_at: null }
+    for (const createdAt of [null, '0000-00-00 00:00:00']) {
+      const row = { id: 'no-created-at', next_run_at: null, created_at: createdAt }
 
-    assert.throws(
-      () => legacyScheduleRowToEpochs(row, ['next_run_at', 'created_at'], 'UTC'),
-      /Cannot migrate schedule "no-created-at": its created_at is empty/
-    )
+      assert.throws(
+        () => legacyScheduleRowToEpochs(row, ['next_run_at', 'created_at'], 'UTC'),
+        /Cannot migrate schedule "no-created-at": its created_at is empty/
+      )
+    }
   })
 })

tests/schedule_dates_migration.spec.ts

@@ -285,6 +285,55 @@ for (const dialect of ['sqlite', 'postgres', 'mysql'] as const) {
         assert.equal(legacy!.nextRunAt!.toISOString(), NEXT_RUN_AT)
         assert.equal(legacy!.lastRunAt!.toISOString(), LAST_RUN_AT)
       })
+
+      test('reads the MySQL zero date as no date', async ({ assert }) => {
+        // Non-strict mode stores the zero date for a date it cannot store.
+        await connection.transaction(async (trx) => {
+          const [[current]] = await trx.raw('select @@session.sql_mode as sql_mode')
+          await trx.raw("set session sql_mode = ''")
+          await trx(TABLE).insert({
+            id: 'legacy',
+            name: 'LegacyJob',
+            payload: '{}',
+            every_ms: 60_000,
+            next_run_at: '0000-00-00 00:00:00',
+            last_run_at: 'not a date',
+          })
+          await trx.raw('set session sql_mode = ?', [current.sql_mode])
+        })
+
+        await new KnexQueueSchemaService(connection).migrateScheduleDates(TABLE, {
+          timezone: WRITER_TIME_ZONE,
+        })
+
+        const legacy = await adapter().getSchedule('legacy')
+        assert.isNull(legacy!.nextRunAt)
+        assert.isNull(legacy!.lastRunAt)
+      })
+
+      test('rejects a zero created_at before changing the table', async ({ assert }) => {
+        await connection.transaction(async (trx) => {
+          const [[current]] = await trx.raw('select @@session.sql_mode as sql_mode')
+          await trx.raw("set session sql_mode = ''")
+          await trx(TABLE).insert({
+            id: 'legacy',
+            name: 'LegacyJob',
+            payload: '{}',
+            every_ms: 60_000,
+            created_at: '0000-00-00 00:00:00',
+          })
+          await trx.raw('set session sql_mode = ?', [current.sql_mode])
+        })
+
+        await assert.rejects(
+          () =>
+            new KnexQueueSchemaService(connection).migrateScheduleDates(TABLE, {
+              timezone: WRITER_TIME_ZONE,
+            }),
+          /Cannot migrate schedule "legacy": its created_at is empty/
+        )
+        assert.match((await connection(TABLE).columnInfo('created_at')).type, /timestamp/i)
+      })
     }
 
     if (dialect === 'postgres') {
@@ -590,6 +639,84 @@ for (const dialect of ['sqlite', 'postgres', 'mysql'] as const) {
 
         await assertMigratedSchedules(assert, adapter(), { exact: CREATED_AT })
       })
+
+      test('reads the MySQL zero date as no date', async ({ assert }) => {
+        // Non-strict mode stores the zero date for a date it cannot store.
+        await connection.connection().execute(async (db) => {
+          const current = await sql<{
+            sqlMode: string
+          }>`select @@session.sql_mode as ${sql.ref('sqlMode')}`.execute(db)
+          await sql`set session sql_mode = ''`.execute(db)
+          await db
+            .insertInto(TABLE)
+            .values({
+              id: 'legacy',
+              name: 'LegacyJob',
+              payload: '{}',
+              every_ms: 60_000,
+              next_run_at: '0000-00-00 00:00:00',
+              last_run_at: 'not a date',
+            })
+            .execute()
+          await sql`set session sql_mode = ${current.rows[0].sqlMode}`.execute(db)
+        })
+
+        await new KyselyQueueSchemaService(connection, { dialect }).migrateScheduleDates(TABLE, {
+          timezone: WRITER_TIME_ZONE,
+        })
+
+        const legacy = await adapter().getSchedule('legacy')
+        assert.isNull(legacy!.nextRunAt)
+        assert.isNull(legacy!.lastRunAt)
+      })
+
+      test('rejects a zero created_at before changing the table', async ({ assert }) => {
+        await connection.connection().execute(async (db) => {
+          const current = await sql<{
+            sqlMode: string
+          }>`select @@session.sql_mode as ${sql.ref('sqlMode')}`.execute(db)
+          await sql`set session sql_mode = ''`.execute(db)
+          await db
+            .insertInto(TABLE)
+            .values({
+              id: 'legacy',
+              name: 'LegacyJob',
+              payload: '{}',
+              every_ms: 60_000,
+              created_at: '0000-00-00 00:00:00',
+            })
+            .execute()
+          await sql`set session sql_mode = ${current.rows[0].sqlMode}`.execute(db)
+        })
+
+        await assert.rejects(
+          () =>
+            new KyselyQueueSchemaService(connection, { dialect }).migrateScheduleDates(TABLE, {
+              timezone: WRITER_TIME_ZONE,
+            }),
+          /Cannot migrate schedule "legacy": its created_at is empty/
+        )
+        assert.match((await columnTypes()).get('created_at')!, /timestamp/i)
+      })
+    }
+
+    if (dialect === 'sqlite') {
+      test('keeps a date in the year 0', async ({ assert }) => {
+        // SQLite stores the text it is given; the migration reads it as UTC.
+        await insertLegacySchedule()
+        await connection
+          .updateTable(TABLE)
+          .set({ next_run_at: '0000-06-01 12:00:00' })
+          .where('id', '=', 'legacy')
+          .execute()
+
+        await new KyselyQueueSchemaService(connection, { dialect }).migrateScheduleDates(TABLE, {
+          timezone: WRITER_TIME_ZONE,
+        })
+
+        const legacy = await adapter().getSchedule('legacy')
+        assert.equal(legacy!.nextRunAt!.toISOString(), '0000-06-01T12:00:00.000Z')
+      })
     }
 
     if (dialect === 'postgres') {