Que contient réellement une colonne timestamp de PostgreSQL ?

Que contient réellement une colonne timestamp de PostgreSQL ?

En deux mots : PostgreSQL stocke aussi bien timestamp que timestamptz sous la forme d’un entier 64 bits représentant le nombre de microsecondes écoulées depuis le 1ᵉʳ janvier 1970 à 00:00:00 UTC. Tout le reste n’est qu’une question d’étiquette lorsqu’on affiche la valeur à des humains.

---

Pourquoi est‑ce si trompeur ?

• Deux colonnes, une date… et deux résultats différents.
• Votre appli insère 2025‑07‑29 10:00, mais l’équipe d’en face lit 02:00.
• Le front renvoie une chaîne ISO qui ne correspond pas au log du back‑end.

Si vous avez déjà vécu ça, cet article est pour vous. On coupe le jargon, on sort des analogies culinaires, on réalise une démo SQL en cinq lignes et on termine avec un test éclair grâce aux convertisseurs Go Tools.

---

Deux bocaux de pêches : l’un nu, l’autre étiqueté

Type SQL	Nom officiel	Valeur stockée	Comportement au SELECT
timestamp	timestamp without time zone	Compteur de microsecondes	Restituée telle quelle : Postgres ne tente aucune conversion
timestamptz	timestamp with time zone	Même compteur	Postgres applique le TimeZone de la session avant d’envoyer le texte

L’analogie

• timestamp : un bocal de pêches sans étiquette d’origine. On sait que c’est un fruit, mais pas d’où il vient.
• timestamptz : un bocal fièrement tamponné « Made in UTC+8 ». À l’ouverture, chacun choisit ou non de convertir la fiche nutritionnelle.

---

Sous le capot : un simple gros nombre

2000‑01‑01 00:00:00 UTC → 0
2000‑01‑01 00:00:01 UTC → 1 000 000

• Unité : microseconde (un millionième de seconde).
• Plage : 4713 av. J.‑C. – 294 276 ap. J.‑C. — de quoi traverser le temps avec Indiana Jones.
• Le stockage est identique pour timestamp et timestamptz ; seule l’interprétation change.

Curieux ? Ouvrez Go Tools → Convertisseur d’époque, collez une date et observez la valeur brute – ou l’inverse.

---

Démo express : 15 secondes chrono

-- Le client pense en heure de Shanghai
SET TimeZone = 'Asia/Shanghai';

CREATE TABLE demo (
  created_ts timestamp,
  created_tz timestamptz
);

INSERT INTO demo VALUES ('2025‑07‑29 10:00', '2025‑07‑29 10:00');

Requête	Résultat	Explication
SELECT created_ts FROM demo;	2025‑07‑29 10:00:00	Valeur brute, sans TZ
SELECT created_tz FROM demo;	2025‑07‑29 10:00:00+08	Étiquette appliquée
Après SET TimeZone = 'UTC';	2025‑07‑29 02:00:00+00	Même instant, autre regard

---

Pièges fréquents & remèdes rapides

1. Chaque utilisateur a sa montre Cause : chaque client définit son propre TimeZone avec timestamptz. Remède : soit tout passer en timestamp et choisir un fuseau de référence, soit forcer SET TimeZone = 'UTC' à la connexion.

2. Conserver l’heure « murale » avec le mauvais type – Les agendas locaux (horaires de magasin, échéances) préfèrent timestamp. – Les flux internationaux (commandes, logs) stockent l’UTC en timestamptz.

3. APIs qui dérivent Expédiez toujours les timestamptz en ISO 8601 avec l’offset (Z ou +08:00). Le front formate selon le navigateur.

Go Tools → Convertisseur de fuseau montre instantanément le même instant vu de New York, Paris ou Tokyo. Collez, vérifiez, déployez.

---

Mémo : quel type choisir ?

Calendrier local → timestamp
Besoin mondial   → timestamptz (stockez en UTC)

• Rapports financiers, plannings de cours → timestamp
• Logs d’audit, commandes e‑commerce → timestamptz

---

Vérification en quelques secondes avec Go Tools

Besoin	Outil	Mode d’emploi
Inspecter la valeur epoch d’une requête	Convertisseur d’époque	Coller 1690622400, cliquer Convert
Comparer deux fuseaux en un coup d’œil	Convertisseur de fuseau	Saisir 10:00 Asia/Shanghai
Nettoyer un JSON rempli de dates	Formateur JSON	Coller la charge utile, cliquer « Beau »

Tous les utilitaires s’exécutent entièrement dans votre navigateur : aucune donnée ne quitte votre machine.

---

En résumé

• Les deux types temporels de Postgres sont simplement des compteurs de microsecondes ; seule l’étiquette fait la différence.
• Se tromper de type mène à des horloges folles et des calculs erronés.
• Avec Go Tools, testez, convertissez et validez en trois clics.

La prochaine fois qu’on vous demande : « Qu’est‑ce qui se cache vraiment dans une colonne timestamp ? » – envoyez ce mémo et nos convertisseurs. Vous économiserez une réunion, peut‑être même un sprint entier.