
The Unix epoch is January 1, 1970 UTC. Go's `time` package provides direct access to epoch timestamps and can convert them back to `time.Time` values.

<ExamplePair>
<ExampleProse>

`t.Unix()` returns the number of seconds elapsed since the Unix epoch. `t.UnixMilli()` and `t.UnixNano()` return milliseconds and nanoseconds respectively. These are plain `int64` values - portable across every language and database.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

func main() {
    now := time.Now()

    fmt.Println(now.Unix())      // e.g. 1714000000
    fmt.Println(now.UnixMilli()) // milliseconds
    fmt.Println(now.UnixNano())  // nanoseconds

    // Construct a specific time
    t := time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)
    fmt.Println(t.Unix()) // 1704067200
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Convert an epoch integer back to `time.Time` with `time.Unix(sec, nsec)`. Always call `.UTC()` immediately to ensure the result is in UTC, regardless of the server's local timezone.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

func main() {
    // Seconds since epoch → time.Time
    ts := int64(1704067200)
    t := time.Unix(ts, 0).UTC()
    fmt.Println(t) // 2024-01-01 00:00:00 +0000 UTC

    // Milliseconds since epoch → time.Time
    ms := int64(1704067200000)
    tms := time.UnixMilli(ms).UTC()
    fmt.Println(tms) // 2024-01-01 00:00:00 +0000 UTC

    // Nanoseconds
    ns := int64(1704067200000000000)
    tns := time.Unix(0, ns).UTC()
    fmt.Println(tns)
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Measure elapsed time precisely by subtracting two epoch values. For benchmarking short operations, prefer nanoseconds. For human-readable durations, convert the difference to a `time.Duration`.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

func doWork() {
    time.Sleep(10 * time.Millisecond)
}

func main() {
    start := time.Now().UnixNano()
    doWork()
    end := time.Now().UnixNano()

    elapsedNs := end - start
    elapsed := time.Duration(elapsedNs)
    fmt.Printf("elapsed: %v\n", elapsed) // e.g. 10.123ms

    // Prefer time.Since for this - it's cleaner
    t := time.Now()
    doWork()
    fmt.Printf("elapsed: %v\n", time.Since(t))
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Store timestamps as UTC Unix seconds (`int64`) in databases for maximum portability - every language and database understands them, they sort correctly, and they never drift with timezone changes. Convert to `time.Time` in UTC immediately after reading from storage, and format for display only at the presentation layer. Never store a `time.Time` directly in SQL without UTC normalization: Go's default `time.Time.String()` includes the local timezone, which produces inconsistent data if your service runs in multiple regions. Use `t.UTC().Format(time.RFC3339)` for string storage or a UTC-aware SQL driver. When receiving epoch timestamps from external APIs, confirm whether the value is in seconds or milliseconds - off-by-1000 bugs produce dates in 1970 or 55,000 years in the future, both of which slip through typical validation.
</InProduction>


Unix epoch seconds and nanoseconds, converting back with time.Unix, and best practices for storing timestamps in databases.

Epoch


Go formats and parses time using a reference time rather than format codes. The reference time is `Mon Jan 2 15:04:05 MST 2006` - a specific moment whose components form a mnemonic: month=1, day=2, hour=3, minute=4, second=5, year=6.

<ExamplePair>
<ExampleProse>

Format a `time.Time` by constructing a layout string from the reference time's components. `time.RFC3339` and similar constants provide commonly used layouts. Custom layouts are built from the same reference components.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

func main() {
    t := time.Date(2024, 3, 15, 14, 30, 0, 0, time.UTC)

    // Predefined layouts
    fmt.Println(t.Format(time.RFC3339))       // 2024-03-15T14:30:00Z
    fmt.Println(t.Format(time.RFC1123))       // Fri, 15 Mar 2024 14:30:00 UTC
    fmt.Println(t.Format(time.DateOnly))      // 2024-03-15
    fmt.Println(t.Format(time.TimeOnly))      // 14:30:00

    // Custom layouts use the reference time components
    fmt.Println(t.Format("January 2, 2006"))           // March 15, 2024
    fmt.Println(t.Format("02 Jan 2006 15:04"))         // 15 Mar 2024 14:30
    fmt.Println(t.Format("3:04 PM on Monday"))         // 2:30 PM on Friday
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Parse a time string with `time.Parse(layout, value)`. The layout must match the reference time pattern. `time.ParseInLocation` parses relative to a specific timezone to avoid silent UTC interpretation.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

func main() {
    // Parse RFC3339 (always includes timezone offset)
    t, err := time.Parse(time.RFC3339, "2024-03-15T14:30:00Z")
    if err != nil {
        panic(err)
    }
    fmt.Println(t) // 2024-03-15 14:30:00 +0000 UTC

    // Parse with a custom layout
    t2, err := time.Parse("January 2, 2006", "March 15, 2024")
    if err != nil {
        panic(err)
    }
    fmt.Println(t2) // 2024-03-15 00:00:00 +0000 UTC

    // Parse in a specific location
    loc, _ := time.LoadLocation("America/New_York")
    t3, _ := time.ParseInLocation("2006-01-02 15:04", "2024-03-15 14:30", loc)
    fmt.Println(t3) // 2024-03-15 14:30:00 -0400 EDT
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Convert between timezones with `t.In(loc)`. `time.UTC` and `time.Local` are pre-loaded locations. Use `time.LoadLocation` for named IANA timezone strings like `"America/Los_Angeles"`.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

func main() {
    utc := time.Date(2024, 3, 15, 18, 0, 0, 0, time.UTC)
    fmt.Println("UTC:", utc.Format(time.RFC3339))

    ny, _ := time.LoadLocation("America/New_York")
    fmt.Println("NYC:", utc.In(ny).Format(time.RFC3339))

    tokyo, _ := time.LoadLocation("Asia/Tokyo")
    fmt.Println("Tokyo:", utc.In(tokyo).Format(time.RFC3339))

    // Format for display without timezone info
    fmt.Println(utc.Format("Mon, 02 Jan 2006 15:04:05"))
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Go's reference-time format string is the most surprising API in the stdlib - the numbers (1 2 3 4 5 6 7) correspond to month, day, hour, minute, second, year, timezone offset. Memorize the mnemonic or keep it in a comment near your format strings. Always parse user-supplied time strings with `time.ParseInLocation` using an explicit `time.Location` - `time.Parse` with a layout that lacks timezone info (like `"2006-01-02"`) interprets the result as UTC, which silently converts a user's "today in Tokyo" to yesterday in UTC. Always call `.UTC()` after parsing before storing. When accepting times from external APIs, validate that the string is RFC3339 - it is the only format that is unambiguous and includes timezone offset. Log and return clear errors when parsing fails; a zero `time.Time{}` is January 1, year 1, which will produce confusing timestamps if silently accepted.
</InProduction>


time.Format with Go's reference time, time.Parse, time.RFC3339 and other constants, and location-aware parsing.

Time Formatting / Parsing


The `time` package provides types and functions for measuring and displaying time. `time.Time` represents an instant in time with nanosecond precision. `time.Duration` represents an elapsed duration as an `int64` nanosecond count.

<ExamplePair>
<ExampleProse>

`time.Now()` returns the current local time. Access individual components with methods like `Year()`, `Month()`, `Day()`, `Hour()`, `Minute()`, `Second()`, and `Weekday()`.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

func main() {
    now := time.Now()
    fmt.Println(now)

    fmt.Println(now.Year(), now.Month(), now.Day())
    fmt.Println(now.Hour(), now.Minute(), now.Second())
    fmt.Println(now.Weekday())
    fmt.Println(now.Unix())     // seconds since epoch
    fmt.Println(now.UnixNano()) // nanoseconds since epoch
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Build `time.Duration` values using named constants: `time.Second`, `time.Minute`, `time.Hour`, etc. Add or subtract a duration from a `time.Time` with `Add`. Subtract two `time.Time` values with `Sub` to get a `Duration`.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

func main() {
    now := time.Now()

    // Add durations to a time
    inAnHour := now.Add(1 * time.Hour)
    fmt.Println(inAnHour)

    yesterday := now.Add(-24 * time.Hour)
    fmt.Println(yesterday)

    // Subtract two times to get a duration
    diff := now.Sub(yesterday)
    fmt.Println(diff)            // 24h0m0s
    fmt.Println(diff.Hours())    // 24
    fmt.Println(diff.Minutes())  // 1440
    fmt.Println(diff.Seconds())  // 86400
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`time.Since(t)` returns the elapsed time since `t`. `time.Until(t)` returns the duration until `t`. Both use the monotonic clock for accuracy. Compare two `time.Time` values with `Before`, `After`, and `Equal`.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

func main() {
    start := time.Now()

    time.Sleep(2 * time.Millisecond) // simulate work

    elapsed := time.Since(start)
    fmt.Printf("elapsed: %v\n", elapsed)

    deadline := time.Now().Add(5 * time.Second)
    fmt.Printf("time until deadline: %v\n", time.Until(deadline))

    t1 := time.Now()
    t2 := t1.Add(time.Second)
    fmt.Println(t1.Before(t2)) // true
    fmt.Println(t1.After(t2))  // false
    fmt.Println(t1.Equal(t1))  // true
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
`time.Time` contains both a wall clock reading and a monotonic clock reading. `time.Since` uses the monotonic clock, which is immune to NTP adjustments and DST transitions - always prefer it for measuring elapsed time. Use the wall clock (from `time.Now()`) for timestamps you store in databases or logs. Never compare two `time.Time` values with `==` when one may have been deserialized from a database: the monotonic component is stripped on round-trips through `time.Time.MarshalJSON` or SQL drivers, making the `Equal` method (which compares only wall time) the correct comparison. In HTTP handlers, record `time.Now()` at the top of the handler to measure end-to-end latency rather than calling `time.Since` with a captured start from middleware, where middleware overhead inflates the measurement.
</InProduction>


time.Time, time.Now, Duration arithmetic, time.Since and time.Until, Add and Sub, and comparisons with Before, After, and Equal.