Adding one month to January 31

time.AddDate(0,1,0) on January 31 normalises to March 3, because February 31 does not exist and Go rolls the surplus days forward. MySQL DATE_ADD clamps the same date to February 28. Both behaviours are documented, both are correct in isolation, and a report built with one against a database built with the other is wrong by up to five days without any error being raised.

A monthly report that is off by three days and raises no error is worse than one that crashes. Here is the whole thing in two runs.

Go, four dates, one afternoon

for _, d := range []time.Time{
    time.Date(2026, 1, 31, 0, 0, 0, 0, time.UTC),
    time.Date(2026, 3, 31, 0, 0, 0, 0, time.UTC),
    time.Date(2026, 8, 31, 0, 0, 0, 0, time.UTC),
    time.Date(2024, 1, 31, 0, 0, 0, 0, time.UTC),
} {
    fmt.Printf("%s +1 -> %s\n", d.Format("2006-01-02"), d.AddDate(0, 1, 0).Format("2006-01-02"))
}
2026-01-31  +1 month -> 2026-03-03   (+2 months -> 2026-03-31)
2026-03-31  +1 month -> 2026-05-01   (+2 months -> 2026-05-31)
2026-08-31  +1 month -> 2026-10-01   (+2 months -> 2026-10-31)
2024-01-31  +1 month -> 2024-03-02   (+2 months -> 2024-03-31)

Every one of those is Go doing what it documents: increment the month, keep the day, then normalise the impossible date forward. January 31 plus one month is “February 31”, which is March 3. In a leap year it is March 2.

Note the two-month column: +2 is correct for these dates. The bug hides precisely because the same function gives a right answer for a different offset.

MySQL, same question

SELECT DATE_ADD('2026-01-31', INTERVAL 1 MONTH) AS jan31_plus1,
       DATE_ADD('2026-03-31', INTERVAL 1 MONTH) AS mar31_plus1,
       LAST_DAY('2026-02-01')                    AS last_day_feb;
+-------------+-------------+--------------+
| jan31_plus1 | mar31_plus1 | last_day_feb |
+-------------+-------------+--------------+
| 2026-02-28  | 2026-04-30  | 2026-02-28   |
+-------------+-------------+--------------+

MySQL clamps: it refuses to invent February 31 and lands on the last real day. Two database dialects and one standard library, all “adding a month”, and January 31 maps to three different dates depending on where the arithmetic happens.

The failure this actually causes

A report that computes its boundary in Go and filters with SQL:

now  := time.Date(2026, 3, 31, 10, 0, 0, 0, time.UTC)  // "run March's report"
from := now.AddDate(0, -1, 0)                          // expect 2026-02-28, get 2026-03-03
rows := db.Query("... WHERE created_at >= ? AND created_at < ?", from, now)
now             = 2026-03-31
AddDate(0,-1,0) = 2026-03-03   <- the window start this report would use

The window the code builds is [March 3, March 31) — it silently drops March 1 and 2 and never covers February at all. No error, no empty page: a number that is short by two days and looks completely plausible.

The fix that survives both layers

Compute the boundary once, in one place, and clamp explicitly:

y, m, _ := now.Date()
monthStart := time.Date(y, m, 1, 0, 0, 0, 0, now.Location())  // 2026-03-01
prevStart := monthStart.AddDate(0, -1, 0)                     // 2026-02-01
// window for "last month": [prevStart, monthStart)
monthStart   = 2026-03-01
prevStart    = 2026-02-01   <- day=1 never overflows

Anchoring to the 1st removes the impossible date from the inputs entirely — you never ask for February 31, so there is nothing to normalise. The day field stays 1 forever, and AddDate becomes boring again. If you must do it in SQL, LAST_DAY() is the clamp, and it is the same clamp MySQL already applies to DATE_ADD.

How you know it worked

  • Test the 31st, not the 15th. A monthly-boundary test that only uses mid-month dates passes against every one of the four implementations above. Add 2026-01-31, 2026-03-31, 2026-08-31 and 2024-01-31 as fixtures.
  • Assert the day count, not the date. “January window = 31 days, February = 28” catches clamping and overflow at the same time, in both directions.
  • Run the same fixture through both layers and diff. In this article that is a 5-day gap (2026-02-28 vs 2026-03-03); anything other than zero is your bug, whatever the layers each claim to be right.

How to undo it

  • Reports already generated: recompute with the clamped rule and compare per-day totals before replacing anything. A boundary shifted by three days moves revenue between months; overwriting the old numbers destroys the evidence of how much.
  • Stored boundaries: if you persist the computed from/to, keep the raw timestamp alongside the derived dates, so a later fix can be re-run instead of guessed.
  • AddDate in a shared helper: change it in one place, then grep for every caller before shipping — the same call is correct for +2 months and wrong for +1, so a spot check will lie to you.

Questions people actually ask

Why does AddDate(0,1,0) return March 3 for January 31?

Because it adds one to the month field and keeps the day field at 31. February 31 does not exist, so Go normalises it to March 3 — and March 2 in a leap year. No error, no warning.

Does MySQL do the same thing?

No. DATE_ADD ignores the 31st and clamps to the last valid day: January 31 plus one month is February 28. So the same business rule produces different dates depending on which layer computes it.

What is the safe way to get "the same day next month"?

Compute the first of the month, add the month, then clamp the day to LAST_DAY of the result. Do it in one place — either all in Go or all in SQL — and never compare a Go-computed boundary against a SQL-computed one.

Which one is right?

Neither is universally right; clamping matches billing and reporting habits. The bug is not the choice, it is having two layers make the choice differently and never testing the last day of a month.

Sources


Last checked: 2026-11-18 · Go output from go1.27.0 on Windows 11; SQL output from MySQL 8.4.13 on Ubuntu 26.04 (WSL). Both blocks on this page are pasted from those runs, including the leap-year case.