Une facture de 99,99 € créée à Paris s'affiche "100.00" pour un client à New York, et un rapport de ventes mensuel compte une transaction du 31 janvier dans le mois de février selon le fuseau horaire du serveur qui génère le rapport. Ces deux bugs ont la même cause structurelle : un schéma de base de données qui modélise les montants et les dates comme des nombres et des horodatages "neutres", alors qu'ils ne le sont jamais dès qu'une application dépasse un seul pays et une seule devise.

Le problème des devises : ne jamais stocker un flottant

Le réflexe le plus dangereux est de stocker un montant en FLOAT ou DOUBLE. Les flottants en base 2 ne représentent pas exactement la plupart des valeurs décimales : 0.1 + 0.2 ne donne pas exactement 0.3 en arithmétique flottante IEEE 754, et accumulé sur des milliers de transactions, l'écart devient un vrai problème de comptabilité, pas une curiosité académique.

-- MAUVAIS : FLOAT accumule des erreurs d'arrondi
CREATE TABLE invoices_bad (
    id BIGSERIAL PRIMARY KEY,
    amount FLOAT NOT NULL
);

-- BON : NUMERIC a une précision exacte, ou montant en unité entière (centimes)
CREATE TABLE invoices (
    id BIGSERIAL PRIMARY KEY,
    amount_minor_units BIGINT NOT NULL,  -- montant en centimes, jamais en unité flottante
    currency_code CHAR(3) NOT NULL REFERENCES currencies(code)
);

Deux approches solides coexistent : stocker un NUMERIC(19, 4) (précision exacte, mais attention aux arrondis lors des opérations) ou stocker un entier en unité mineure (centimes pour l'euro, mais attention : toutes les devises n'ont pas deux décimales - le yen japonais (JPY) n'en a aucune, le dinar koweïtien (KWD) en a trois). L'approche par entier en unité mineure, popularisée par des bibliothèques comme Stripe ou Money pattern de Martin Fowler, évite complètement les problèmes d'arrondi flottant et force à expliciter la devise associée à chaque montant.

CREATE TABLE currencies (
    code CHAR(3) PRIMARY KEY,       -- ISO 4217
    minor_unit_digits SMALLINT NOT NULL  -- 2 pour EUR/USD, 0 pour JPY, 3 pour KWD
);

Le piège du montant sans devise associée

Un montant stocké sans sa devise (une colonne amount dans une table où la devise est "implicite" ou définie globalement pour l'application) devient un bug latent dès que l'application s'étend à un deuxième marché. La règle structurelle est simple : chaque montant stocké porte sa propre devise, dans la même ligne, jamais déduite d'une configuration globale ou d'un join fragile.

-- MAUVAIS : la devise est implicite, supposée fixe pour toute l'application
CREATE TABLE payments_bad (
    id BIGSERIAL PRIMARY KEY,
    amount NUMERIC(19,4) NOT NULL
);

-- BON : la devise voyage avec le montant
CREATE TABLE payments (
    id BIGSERIAL PRIMARY KEY,
    amount_minor_units BIGINT NOT NULL,
    currency_code CHAR(3) NOT NULL REFERENCES currencies(code),
    exchange_rate_to_base NUMERIC(19,10),  -- taux au moment de la transaction, pour reporting
    recorded_at TIMESTAMPTZ NOT NULL
);

Le exchange_rate_to_base capturé au moment de la transaction (et non recalculé a posteriori) est essentiel pour tout reporting financier historique : un rapport de ventes de janvier doit utiliser le taux de change de janvier, pas le taux du jour où le rapport est généré. Recalculer après coup avec le taux courant produit des rapports qui changent silencieusement de valeur selon la date de consultation.

Le problème des fuseaux horaires : TIMESTAMP vs TIMESTAMPTZ

PostgreSQL propose deux types distincts, et confondre les deux est la source la plus fréquente de bugs temporels :

  • TIMESTAMP (sans fuseau) : stocke une date et une heure "nues", sans aucune information de fuseau. PostgreSQL ne fait aucune conversion.
  • TIMESTAMPTZ (avec fuseau) : stocke en réalité un instant absolu en UTC interne, et affiche/convertit selon le fuseau de la session au moment de la lecture.
-- MAUVAIS : TIMESTAMP perd l'information de fuseau au moment de l'écriture
CREATE TABLE events_bad (
    id BIGSERIAL PRIMARY KEY,
    occurred_at TIMESTAMP NOT NULL  -- "2025-11-20 14:30:00" dans quel fuseau ?
);

-- BON : TIMESTAMPTZ stocke un instant absolu non ambigu
CREATE TABLE events (
    id BIGSERIAL PRIMARY KEY,
    occurred_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
SET TIME ZONE 'Europe/Paris';
INSERT INTO events (occurred_at) VALUES ('2025-11-20 14:30:00');
-- Stocké en interne comme 2025-11-20 13:30:00 UTC

SET TIME ZONE 'America/New_York';
SELECT occurred_at FROM events;
-- Affiché comme 2025-11-20 08:30:00-05

TIMESTAMPTZ ne stocke jamais le fuseau lui-même : il convertit toujours en UTC à l'écriture et reconvertit à la lecture selon le fuseau de session. C'est précisément ce qu'on veut pour un horodatage d'événement (paiement effectué, commande créée) : un instant absolu, affiché localement selon qui consulte.

Le piège spécifique : les dates métier "sans heure" (anniversaire, échéance)

Pour une date de naissance ou une échéance contractuelle, qui n'a pas de composante horaire et doit rester identique peu importe le fuseau du lecteur, TIMESTAMPTZ est le mauvais choix : convertir "1990-05-15" en UTC puis reconvertir dans un fuseau différent peut faire glisser la date d'un jour. Le bon type est DATE, sans aucune notion de fuseau :

CREATE TABLE contracts (
    id BIGSERIAL PRIMARY KEY,
    due_date DATE NOT NULL,          -- pas d'heure, pas de fuseau : "2025-12-01" reste "2025-12-01" partout
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()  -- instant précis de création, avec fuseau
);

Diagnostiquer un bug de fuseau existant

Le symptôme typique : un rapport d'activité "par jour" compte des événements proches de minuit dans le mauvais jour selon qui consulte le rapport. Pour vérifier, comparer le fuseau de la session au moment du calcul d'agrégation avec le fuseau attendu par l'utilisateur métier :

SHOW timezone;

-- Agrégation correcte : convertir explicitement vers le fuseau de l'utilisateur
-- AVANT de tronquer à la journée, jamais après
SELECT
    date_trunc('day', occurred_at AT TIME ZONE 'Europe/Paris') AS business_day,
    count(*)
FROM events
GROUP BY business_day
ORDER BY business_day;

Tronquer directement occurred_at sans conversion explicite vers le fuseau métier revient à utiliser le fuseau par défaut de la session, qui dépend de la configuration du serveur ou du driver de connexion, un détail totalement invisible dans le code applicatif qui appelle la requête.

Les arrondis lors de la conversion : où l'argent "disparaît"

Même avec des montants stockés correctement en unité mineure entière, convertir entre devises introduit un nouveau risque : l'arrondi. Diviser un montant en trois parts égales, ou convertir un montant via un taux de change, produit presque toujours un résultat qui ne tombe pas exactement sur une unité mineure entière.

-- Convertir 100,00 EUR en USD avec un taux de 1.0847
-- 100.00 * 1.0847 = 108.47 -> arrondi simple, pas de problème ici
-- Mais répartir 100.01 EUR entre 3 bénéficiaires égaux :
-- 100.01 / 3 = 33.336666... -> impossible de répartir exactement en centimes

La règle à appliquer systématiquement est de ne jamais laisser un calcul de répartition ou de conversion perdre ou créer de la monnaie de façon silencieuse. La technique standard (utilisée notamment par Stripe pour la répartition de paiements multi-destinataires) consiste à calculer chaque part par troncature, puis à attribuer le reliquat d'arrondi à la dernière part ou à un bénéficiaire désigné, de façon à ce que la somme des parts égale exactement le montant d'origine, au centime près :

-- Répartir 10001 centimes (100,01 €) entre 3 parts égales
-- Part 1 : floor(10001 / 3) = 3333
-- Part 2 : floor(10001 / 3) = 3333
-- Part 3 : 10001 - 3333 - 3333 = 3335 (absorbe le reliquat)
-- Total : 3333 + 3333 + 3335 = 10001 -> exact, rien n'a disparu

Ce détail paraît mineur à l'échelle d'une transaction, mais devient un vrai problème de réconciliation comptable à l'échelle de millions de transactions, où des centimes systématiquement perdus ou créés par une mauvaise stratégie d'arrondi finissent par représenter des écarts significatifs et difficiles à expliquer lors d'un audit financier.

Quand la solution simple ne suffit pas

Pour une application qui doit afficher des horaires récurrents (horaires d'ouverture, rappels récurrents) à travers des changements d'heure d'été/hiver, stocker un TIMESTAMPTZ fixe ne suffit pas : un rappel "tous les jours à 9h, heure de Paris" doit être recalculé par rapport au nom de fuseau IANA (Europe/Paris), pas par rapport à un décalage UTC figé, parce que ce décalage change deux fois par an. Stocker Europe/Paris comme chaîne et recalculer l'horaire UTC à chaque occurrence, plutôt que de figer un décalage, est la seule approche qui reste correcte sur la durée.

À retenir

Un montant sans devise associée et un horodatage sans fuseau explicite sont tous les deux des bugs qui ne se révèlent qu'à l'usage international, jamais en développement local avec un seul utilisateur dans un seul fuseau. La règle structurelle à appliquer dès la conception du schéma : chaque montant stocké porte sa devise sur la même ligne, chaque instant stocké utilise TIMESTAMPTZ, et chaque date métier sans heure utilise DATE, jamais TIMESTAMP nu.