Fusi Orari e Timestamp: Gestire il Tempo nei Dati Senza Errori
Un istante, tre modi di scriverlo
Un ordine viene registrato alle 14:30 a Milano. È lo stesso istante delle 13:30 a Londra e delle 08:30 a New York. Tre stringhe diverse, un solo evento sulla linea del tempo. Buona parte dei bug "temporali" nasce dal confondere tre concetti che sembrano la stessa cosa ma non lo sono:
- l'istante: un punto unico sulla linea del tempo, uguale per tutti gli osservatori;
- la rappresentazione locale: come quell'istante viene scritto in un certo fuso orario;
- la data di calendario: il giorno a cui un evento appartiene secondo una convenzione di business.
Un ordine ha un istante preciso. La giornata di vendita a cui appartiene, invece, dipende dal negozio: un ordine delle 23:50 a Milano appartiene al giorno milanese, anche se in UTC è già il giorno dopo.
C'è poi un dettaglio che complica tutto: "Europe/Rome" non è "+01:00". Un offset fisso è un numero; un fuso IANA è un insieme di regole che cambiano nel tempo, ora legale inclusa. Se salvi "+01:00" hai salvato una fotografia, se salvi "Europe/Rome" hai salvato la regola.
PostgreSQL: timestamp, timestamptz e la conversione esplicita
PostgreSQL offre tipi diversi proprio perché i concetti sono diversi.
| Tipo | Cosa contiene | Uso tipico |
|---|---|---|
timestamp | data e ora "nude", senza offset | orari locali, ricorrenze, appuntamenti |
timestamptz | un istante, salvato internamente in UTC | ordini, log, click, eventi |
date | solo il giorno | giorno contabile, festività |
interval | una durata | differenze, SLA, tempi di consegna |
Il primo malinteso da sfatare: timestamptz non salva il fuso orario. Salva un istante in UTC e lo mostra convertito nel fuso della sessione. La stessa riga appare diversa a seconda di chi la legge:
SET TimeZone = 'UTC';
SELECT creato_il FROM ordini LIMIT 1; -- 2025-03-30 01:30:00+00
SET TimeZone = 'Europe/Rome';
SELECT creato_il FROM ordini LIMIT 1; -- 2025-03-30 03:30:00+02
È lo stesso valore. Il fuso è una lente, non un dato.
Attenzione a AT TIME ZONE, che fa due cose opposte a seconda del tipo di partenza:
-- da timestamptz a timestamp: converte nell'ora locale
SELECT now() AT TIME ZONE 'Europe/Rome';
-- da timestamp a timestamptz: interpreta l'orario come locale
SELECT timestamp '2025-03-30 03:30' AT TIME ZONE 'Europe/Rome';
Da qui la regola pratica: timestamptz per gli eventi, timestamp per le ricorrenze, date per i giorni contabili. Se ti accorgi di dover correggere a mano un offset per far quadrare un report, probabilmente hai scelto il tipo sbagliato.
L'ora legale: il caso che rompe i conti
Due volte l'anno il tempo locale non è una funzione monotona. In Italia, nel 2025, succede questo:
| Momento | Cosa accade | Conseguenza |
|---|---|---|
| 30 marzo 2025, 02:00 | si passa a 03:00 | l'orario 02:30 non esiste |
| 26 ottobre 2025, 03:00 | si torna a 02:00 | l'orario 02:30 esiste due volte |
Il primo caso rompe le conversioni: 2025-03-30 02:30 Europe/Rome non corrisponde a nessun istante reale. Il secondo rompe le aggregazioni: un GROUP BY sull'ora locale conta due volte l'ora 02:00.
Il problema più insidioso però non è la conversione, è l'aritmetica. Confronta:
-- Durata reale tra due istanti (23 ore: la notte è più corta)
SELECT timestamptz '2025-03-30 03:00 Europe/Rome'
- timestamptz '2025-03-29 03:00 Europe/Rome'; -- 23:00:00
-- Differenza tra due orari locali "nudi" (24 ore)
SELECT timestamp '2025-03-30 03:00' - timestamp '2025-03-29 03:00'; -- 24:00:00
Entrambi i risultati sono corretti, ma rispondono a domande diverse. Se stai calcolando quanto tempo è passato davvero — un tempo di consegna, una latenza, un tasso orario — ti servono gli istanti. Se stai calcolando quante ore di orologio separano due appuntamenti, il secondo conto va bene.
Molti bug nascono dal mescolare i due approcci: sottrarre orari locali per misurare una durata reale, oppure sommare +24h a un istante per ottenere "lo stesso orario di domani". Il secondo caso è un classico degli scheduler: +24h a cavallo del cambio d'ora sposta l'esecuzione di un'ora.
Python: naive, aware e la trappola dell'aritmetica
In Python la distinzione ha un nome: naive contro aware. Un datetime naive non sa nulla del fuso, uno aware porta con sé un tzinfo.
from datetime import datetime, timezone
from zoneinfo import ZoneInfo
rome = ZoneInfo("Europe/Rome")
sbagliato = datetime.now() # naive: da evitare
adesso_utc = datetime.now(timezone.utc) # aware: corretto
adesso_roma = datetime.now(rome) # aware, ora locale
Con zoneinfo (libreria standard da Python 3.9) la conversione resta corretta anche attraverso l'ora legale:
creato = datetime(2025, 3, 30, 1, 30, tzinfo=timezone.utc)
print(creato.astimezone(rome)) # 2025-03-30 03:30:00+02:00
a = datetime(2025, 3, 29, 3, 0, tzinfo=rome)
b = datetime(2025, 3, 30, 3, 0, tzinfo=rome)
print(b - a) # 23:00:00, durata reale
Tre abitudini da prendere subito:
- usare sempre
datetime.now(timezone.utc)per gli istanti, maidatetime.now(); - convertire in ora locale solo in fase di presentazione o di aggregazione per giorno;
- per gli orari ambigui (quelli che esistono due volte) ricordarsi dell'attributo
fold, che indica quale delle due occorrenze si intende.
Se lavori ancora con pytz invece di zoneinfo, ricorda che replace(tzinfo=tz) è sbagliato e serve tz.localize(dt). Con zoneinfo il problema non esiste.
Nel retail il giorno è locale
In un negozio il giorno di vendita è definito dall'orario locale del punto vendita, non da UTC. Aggregando per giorno UTC, le vendite fatte dopo le 22:00 in Italia finiscono nel giorno successivo e i totali non tornano con la chiusura di cassa.
La struttura che funziona è semplice: salva l'istante in UTC e il fuso come attributo del negozio.
CREATE TABLE negozi (
id int PRIMARY KEY,
nome text NOT NULL,
fuso text NOT NULL -- es. 'Europe/Rome', 'America/New_York'
);
CREATE TABLE ordini (
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
negozio_id int NOT NULL REFERENCES negozi(id),
creato_il timestamptz NOT NULL DEFAULT now(),
importo numeric(12,2) NOT NULL
);
L'aggregazione per giorno locale diventa una conversione esplicita, senza offset scritti a mano:
SELECT
(o.creato_il AT TIME ZONE n.fuso)::date AS giorno_locale,
sum(o.importo) AS vendite
FROM ordini o
JOIN negozi n ON n.id = o.negozio_id
WHERE o.creato_il >= timestamptz '2025-03-01 00:00:00 Europe/Rome'
AND o.creato_il < timestamptz '2025-04-01 00:00:00 Europe/Rome'
GROUP BY 1
ORDER BY 1;
Lo stesso schema funziona per un negozio a New York senza cambiare una riga di SQL: cambia solo il valore di fuso. E i confini del periodo sono espressi in ora locale, perché è così che ragiona chi legge il report.
Nei data warehouse è spesso utile materializzare il giorno locale come colonna, calcolato una volta sola in fase di caricamento. Costa spazio, ma semplifica query e report.
Ricorrenze e orari di apertura
Gli eventi puntuali vanno in UTC. Le ricorrenze no.
Un negozio che apre alle 08:00 apre a quell'ora ogni giorno, indipendentemente dall'ora legale. Se salvi "07:00 UTC" come orario di apertura, dopo il cambio d'ora il negozio risulterà aprire un'ora prima o un'ora dopo.
| Tipo di dato | Cosa salvare | Esempio |
|---|---|---|
| Evento puntuale | istante UTC (timestamptz) | apertura effettiva della cassa |
| Ricorrenza | ora locale + fuso IANA | apertura prevista: 08:00 Europe/Rome |
| Giorno contabile | date senza ora | chiusura del 30 marzo |
Lo stesso vale per i calendari: le festività sono locali, e un calendario condiviso tra Paesi diversi va costruito come insieme di calendari per fuso, non come una lista unica di date.
Pipeline, cron e finestre di calcolo
Nelle pipeline il tempo è una variabile di partizione, e qui si concentrano i problemi.
Un job schedulato "alle 02:00 ora locale" si comporta male due volte l'anno: a marzo quell'ora non esiste e molti cron la saltano, a ottobre esiste due volte e il job può girare due volte. Se il job non è idempotente, il secondo giro duplica i dati.
Le contromisure che funzionano:
- schedula in UTC e calcola dentro il job la finestra locale che ti interessa;
- passa la finestra come parametro esplicito (inizio e fine in UTC), invece di leggere "adesso" dentro la trasformazione;
- rendi il job idempotente: rieseguirlo sulla stessa finestra deve produrre lo stesso risultato, non duplicati;
- scegli consapevolmente se la partizione è per giorno UTC o giorno locale, e documentalo: entrambe sono scelte legittime, mescolarle nello stesso dataset no.
Un dettaglio che sfugge spesso: la finestra di un giorno locale non è lunga 24 ore. In corrispondenza del cambio d'ora dura 23 o 25 ore. Se il codice assume fine = inizio + 24h, il giorno del cambio perderà o raccoglierà un'ora di dati.
Test e checklist
I bug sui fusi orari si testano, non si sperano. Una checklist minima:
- test sul cambio d'ora: una notte "corta" e una "lunga" tra i casi di test;
- test a cavallo di mezzanotte: un evento alle 23:30 locali deve finire nel giorno locale corretto;
- test su fine anno e su un 29 febbraio;
- almeno due fusi diversi nel dataset di test, non solo il tuo;
- nessun offset scritto a mano nel codice: sempre nomi IANA;
- nessun
datetime.now()naive nelle pipeline; - confini di periodo espliciti in UTC, con la conversione documentata.
Un solo test che copre il 30 marzo 2025 e il 26 ottobre 2025 copre già la maggior parte dei casi che rompono la produzione.
Conclusione
Gestire il tempo nei dati è meno complicato di quanto sembri, se si tengono ferme poche distinzioni:
- istante, rappresentazione locale e giorno contabile sono tre cose diverse: vanno salvate in tipi diversi;
- in PostgreSQL usa
timestamptzper gli eventi,timestampper le ricorrenze,dateper i giorni contabili, ricordando chetimestamptzsalva UTC e non un fuso; - l'ora legale rende il tempo locale non monotono: giornate da 23 o 25 ore, orari che non esistono o esistono due volte;
- mai aritmetica su orari locali per misurare durate reali: usa gli istanti;
- nel retail il giorno di vendita è locale: salva UTC, tieni il fuso come attributo del negozio, converti in query;
- schedula in UTC, parametrizza la finestra, rendi i job idempotenti;
- scrivi test che attraversano i cambi d'ora: sono i casi che rompono le pipeline.
Un'ultima regola pratica: se in un report due numeri non tornano e la differenza è "circa un'ora", la prima cosa da controllare non è la query. È il fuso.
Foto di copertina di Renel Wackett su Unsplash.