Package dev.frostlake.executor

Class StatementClock

java.lang.Object
dev.frostlake.executor.StatementClock
public final class StatementClock extends Object
The one instant a statement calls "now".

Snowflake reads its clock once per STATEMENT, not once per row and not once per transaction — live-verified: an INSERT selecting CURRENT_TIMESTAMP() over five generated rows stores one distinct value, CURRENT_TIMESTAMP() = CURRENT_TIMESTAMP() within a statement is TRUE, and two statements inside one BEGIN…COMMIT get DIFFERENT times. Reading the wall clock per call, as the temporal functions used to, produced a different value for every row.

Pinning the instant also makes the write-ahead log replayable: the log stores SQL text and recovery re-executes it, so a per-call clock made CURRENT_TIMESTAMP resolve to the RECOVERY time rather than the original. The log records the pinned instant and pin(java.time.Instant) puts it back, so a replayed row keeps the value it was written with.

Scoped to the thread because the engine runs a session's statements on the caller's thread; the pin is taken by the OUTERMOST statement only. A procedural block's INNER statements each advance the pin to a fresh reading (advance()) — live gives every statement inside a block its own time — except during write-ahead-log replay, where the whole block keeps its recorded instant.

What is pinned is an INSTANT, not a wall-clock reading, because one instant has two renderings and Snowflake uses both: CURRENT_TIMESTAMP and LOCALTIMESTAMP answer in the session's zone while SYSDATE answers in UTC. Live-verified with the session on America/Los_Angeles — SYSDATE() = 2026-08-07 13:57:23.484 against CURRENT_TIMESTAMP() = 2026-08-07 06:57:23.484 -0700, the same instant seven hours apart, so SYSDATE() = CURRENT_TIMESTAMP() is FALSE; set the session to UTC and it is TRUE. SYSDATE is also typed TIMESTAMP_NTZ where CURRENT_TIMESTAMP is TIMESTAMP_LTZ.

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    advance()
    Move the pinned instant forward to a fresh reading — the boundary between two statements INSIDE an outer one: a procedural block's statements each read their own clock (live-verified).
    static Instant
    instant()
    The pinned instant, or a fresh reading when nothing is pinned.
    static boolean
    isPinned()
    Whether a statement instant is currently pinned.
    static LocalDateTime
    now()
    The current statement's reading in the session's zone — what CURRENT_TIMESTAMP, LOCALTIMESTAMP, CURRENT_DATE, CURRENT_TIME, GETDATE and NOW answer with.
    static LocalDateTime
    nowUtc()
    The same instant in UTC — what SYSDATE answers with.
    static Instant
    pin(Instant instant)
    Pin this statement's instant, returning what was pinned before so the caller can restore it.
    static void
    restore(Instant previous)
    Put back whatever pin(java.time.Instant) displaced; a null restores the unpinned state.
    static void
    setReplay(boolean replaying)
    Write-ahead-log replay marker: while set, advance() keeps the recorded instant.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • advance

      public static void advance()
      Move the pinned instant forward to a fresh reading — the boundary between two statements INSIDE an outer one: a procedural block's statements each read their own clock (live-verified). A no-op when nothing is pinned (the fresh-read path already applies) and during write-ahead-log replay, where the outer statement keeps its recorded instant.

    • setReplay

      public static void setReplay(boolean replaying)
      Write-ahead-log replay marker: while set, advance() keeps the recorded instant.

    • now

      public static LocalDateTime now()
      The current statement's reading in the session's zone — what CURRENT_TIMESTAMP, LOCALTIMESTAMP, CURRENT_DATE, CURRENT_TIME, GETDATE and NOW answer with. The engine's session zone IS UTC (its TIMEZONE parameter), so this renders the instant in UTC — never the host's zone, whose offset would otherwise leak into every epoch extraction (DATE_PART(EPOCH_SECOND, CURRENT_TIMESTAMP()) answers the true instant on a real account, live-verified). Unpinned, the clock is read afresh so a function called outside any statement still answers.

    • nowUtc

      public static LocalDateTime nowUtc()
      The same instant in UTC — what SYSDATE answers with.

    • instant

      public static Instant instant()
      The pinned instant, or a fresh reading when nothing is pinned.

    • pin

      public static Instant pin(Instant instant)
      Pin this statement's instant, returning what was pinned before so the caller can restore it. A null argument pins the wall clock. Re-entrant callers pass the returned value back to restore(java.time.Instant).

    • isPinned

      public static boolean isPinned()
      Whether a statement instant is currently pinned.

    • restore

      public static void restore(Instant previous)
      Put back whatever pin(java.time.Instant) displaced; a null restores the unpinned state.