Torna al blog
Fusi Orari e Timestamp: Gestire il Tempo nei Dati Senza Errori

Fusi Orari e Timestamp: Gestire il Tempo nei Dati Senza Errori

9 min di lettura1 visualizzazioni
di Marco Salmaso
Un istante è uno solo, ma si può scrivere in molti modi: fusi orari, ora legale e timestamp mal riposti sono tra le cause più comuni di dati sbagliati. Guida pratica a timestamp e timestamptz in PostgreSQL, a zoneinfo in Python e alle aggregazioni per giorno locale nel retail.

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.

TipoCosa contieneUso tipico
timestampdata e ora "nude", senza offsetorari locali, ricorrenze, appuntamenti
timestamptzun istante, salvato internamente in UTCordini, log, click, eventi
datesolo il giornogiorno contabile, festività
intervaluna duratadifferenze, 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:

MomentoCosa accadeConseguenza
30 marzo 2025, 02:00si passa a 03:00l'orario 02:30 non esiste
26 ottobre 2025, 03:00si torna a 02:00l'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, mai datetime.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 datoCosa salvareEsempio
Evento puntualeistante UTC (timestamptz)apertura effettiva della cassa
Ricorrenzaora locale + fuso IANAapertura prevista: 08:00 Europe/Rome
Giorno contabiledate senza orachiusura 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 timestamptz per gli eventi, timestamp per le ricorrenze, date per i giorni contabili, ricordando che timestamptz salva 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.