PostgreSQL 19 : les nouvelles fonctionnalités que tout développeur d'API doit connaître

PostgreSQL 19 apporte ON CONFLICT DO SELECT pour les points de terminaison de type get-or-create, WAIT FOR LSN pour garantir la lecture de vos propres écritures sur les réplicas, REPACK (CONCURRENTLY), la sortie JSON depuis COPY, ainsi qu'une liste de changements par défaut à vérifier avant de...

INEZA Felin-Michel

INEZA Felin-Michel

20 November 2026

PostgreSQL 19 : les nouvelles fonctionnalités que tout développeur d'API doit connaître

Apidog pour les entreprises

Déploiement sur site

SSO & RBAC

Conforme SOC 2

Découvrir Apidog Enterprise

Les nouvelles fonctionnalités de PostgreSQL 19 les plus importantes pour les développeurs d'API : INSERT ... ON CONFLICT DO SELECT pour des endpoints get-or-create en une seule instruction, WAIT FOR LSN pour le read-your-writes sur les réplicas, REPACK (CONCURRENTLY) pour un nettoyage du bloat en ligne, la sortie JSON de COPY, les nouvelles méthodes de chaînes jsonpath, et des vérifications de clés étrangères plus rapides sur les insertions en masse.

Ce guide couvre ce qui change dans vos handlers, vos réplicas et votre plan de mise à niveau. Chaque exemple de syntaxe provient des notes de version de PostgreSQL 19 et des pages de référence.

Ce qu'il faut retenir des nouveautés de PostgreSQL 19

PostgreSQL 19 est la version majeure annuelle de la base de données open source, annoncée par le PostgreSQL Global Development Group le 19 novembre 2026. Elle ajoute les insertions get-or-create, l'attente sur les réplicas pour le read-your-writes, le repacking de tables en ligne, les conseils de plan et la réplication logique des séquences, et elle modifie plusieurs valeurs par défaut à vérifier avant de procéder à la mise à niveau.

Fonctionnalité Ce qu'elle remplace Où vous la ressentirez
ON CONFLICT DO SELECT Les boucles SELECT puis INSERT avec gestion des conflits Endpoints POST et d'inscription idempotents
WAIT FOR LSN Le routage persistant des lectures vers le primaire Réplicas de lecture derrière une API
REPACK (CONCURRENTLY) VACUUM FULL, CLUSTER, pg_repack Tables actives gonflées, sans interruption de service
COPY ... (FORMAT json) La conversion de lignes en JSON dans le code applicatif Endpoints d'export et de téléchargement en masse
Méthodes de chaînes jsonpath Le post-traitement des JSONB dans le code applicatif Filtrage et normalisation des colonnes JSON
pg_plan_advice + pg_stash_advice La réécriture de requêtes pour orienter le planificateur Régressions de plan en production
Publications FOR ALL SEQUENCES La réinitialisation manuelle des séquences après basculement Mises à niveau blue-green via réplication logique

L'annonce officielle de la version mentionne également l'aspiration des index en parallèle et les workers d'E/S asynchrones à mise à l'échelle automatique. Ils ne changent pas le SQL envoyé par votre API, donc cet article ne les traite pas.

ON CONFLICT DO SELECT : get-or-create en une seule instruction

Toute API possède un endpoint qui doit renvoyer une ligne qu'elle existe ou non : enregistrer un appareil, créer une étiquette, démarrer un paiement idempotent. Avant la version 19, vous exécutiez un SELECT puis un INSERT (et perdiez les courses sous charge), ou écriviez un faux ON CONFLICT DO UPDATE juste pour déclencher RETURNING, ce qui crée une nouvelle version de ligne pour rien.

PostgreSQL 19 ajoute une quatrième action de conflit. La référence de INSERT l'appelle une « insertion idempotente ou get or create » :

INSERT INTO distributors (did, dname) VALUES (11, 'Global Electronics')
    ON CONFLICT (did) DO SELECT
    RETURNING *;

Si did = 11 est libre, la ligne est insérée et renvoyée. Si elle est déjà prise, la ligne existante est renvoyée et rien n'est modifié. Trois règles issues de la documentation :

Flowchart of a POST /users request using INSERT ON CONFLICT (email) DO SELECT RETURNING: no conflict inserts and returns the row (201), a conflict returns the existing row unmodified (200)

Votre handler a généralement besoin de savoir quelle branche s'est exécutée, afin de répondre 201 Created ou 200 OK. La documentation indique que les anciennes valeurs de RETURNING sont non-NULL en cas de conflit ; une seule colonne suffit donc :

INSERT INTO users (email, name) VALUES ($1, $2)
    ON CONFLICT (email) DO SELECT
    RETURNING *, (old.id IS NULL) AS created;

Besoin de verrouiller la ligne existante avant de toucher aux tables associées ? Ajoutez une clause de verrouillage : ON CONFLICT (did) DO SELECT FOR UPDATE RETURNING *. Vous pouvez aussi filtrer avec WHERE, par exemple DO SELECT WHERE d.dname != EXCLUDED.dname, et seules les lignes qui passent le filtre sont renvoyées.

Privilèges : DO SELECT nécessite SELECT sur la table, et les formes FOR UPDATE/FOR SHARE exigent aussi UPDATE sur au moins une colonne.

WAIT FOR LSN : read-your-writes sur les réplicas

Le bug classique des réplicas : un utilisateur enregistre son profil, le GET suivant tombe sur un réplica asynchrone qui n'a pas encore rejoué la modification, et les anciennes données reviennent. La plupart des équipes épinglent les lectures sur le primaire après une écriture, ce qui gaspille le réplica.

PostgreSQL 19 ajoute la commande WAIT FOR. Après une écriture, récupérez la position WAL du primaire :

UPDATE movie SET genre = 'Dramatic' WHERE genre = 'Drama';
SELECT pg_current_wal_insert_lsn();   -- returns 0/0306EE20

Stockez ce LSN dans la session de l'utilisateur (Simon Willison suggère un cookie signé dans son article). À la requête suivante, exécutez ceci sur le réplica avant la lecture :

WAIT FOR LSN '0/0306EE20' WITH (TIMEOUT '100ms', NO_THROW);
SELECT * FROM movie WHERE genre = 'Drama';
Sequence diagram: API server commits an UPDATE on the primary, reads pg_current_wal_insert_lsn 0/0306EE20, stores it in the session, then on the next request sends WAIT FOR LSN to the read replica, gets success, and SELECTs the fresh row

Les détails qui comptent dans une API :

  1. Modes. Le mode par défaut MODE 'standby_replay' attend que la modification soit appliquée, ce qui correspond au besoin du read-your-writes. standby_write, standby_flush et primary_flush existent pour des vérifications de durabilité.
  2. Délais d'attente. Sans TIMEOUT, ou avec TIMEOUT '0', il attend indéfiniment. Définissez toujours un délai dans les chemins de requête.
  3. NO_THROW. Sans lui, un dépassement de délai déclenche une erreur et annule votre transaction. Avec lui, vous obtenez un statut success, timeout ou not in recovery, et vous pouvez basculer sur le primaire.
  4. Emplacement. WAIT doit être une commande de premier niveau, pas à l'intérieur d'une fonction ou d'un bloc DO. Exécutez-la hors transaction ou en première instruction, avant toute opération prenant un verrou, sinon elle est rejetée.

REPACK (CONCURRENTLY) remplace VACUUM FULL pour les tables actives

Les tables derrière des endpoints très sollicités, comme sessions ou webhook_deliveries, gonflent vite. VACUUM FULL et CLUSTER corrigent cela mais verrouillent la table. PostgreSQL 19 ajoute une option en ligne :

REPACK (CONCURRENTLY) webhook_deliveries;
REPACK (CONCURRENTLY, ANALYZE) orders USING INDEX orders_created_at_idx;

Les notes de version indiquent que REPACK (CONCURRENTLY) récupère l'espace et peut réorganiser une table selon un index sans bloquer les lectures ni les écritures. VACUUM FULL et CLUSTER sont conservés pour compatibilité. Suivez la progression dans la nouvelle vue pg_stat_progress_repack, et surveillez le nouveau paramètre serveur max_repack_replication_slots lors du réglage du cluster.

Sortie JSON de COPY et nouvelles méthodes de chaînes jsonpath

Les endpoints d'export transmettent souvent les lignes à travers le code applicatif juste pour les convertir en JSON. COPY TO peut désormais le faire directement dans la base, selon la référence de COPY :

COPY (SELECT * FROM (VALUES(1),(2)) val(id)) TO STDOUT (FORMAT JSON, FORCE_ARRAY);

Cela affiche [, {"id":1}, ,{"id":2} et ] sur des lignes séparées, si bien que la sortie forme un tableau JSON valide. Sans FORCE_ARRAY, vous obtenez un objet JSON par ligne, compatible NDJSON. Un NULL SQL devient null JSON, et le format json ne fonctionne qu'avec COPY TO.

Pour les colonnes JSONB, jsonpath gagne des méthodes de chaînes : lower(), upper(), initcap(), ltrim(), rtrim(), btrim(), replace() et split_part(). La documentation montre :

jsonb_path_query('"TOM"', '$.lower()')                  -- "tom"
jsonb_path_query('" hello "', '$.btrim()')              -- "hello"
jsonb_path_query('"abc,def,ghi,jkl"', '$.split_part(",", 3)')  -- "ghi"

Les notes de version les marquent comme immuables, et elles permettent de normaliser un champ JSONB (le tronquer, le mettre en minuscules, le découper) directement dans la requête plutôt que dans votre handler.

Par ailleurs, json_array() sur zéro ligne renvoie désormais [] au lieu de NULL, ce qui peut casser un client qui teste la valeur null.

Autres changements de PostgreSQL 19 que les équipes API doivent connaître

Changements incompatibles à vérifier avant la mise à niveau

La section migration des notes de version liste des changements qui peuvent affecter une API sans qu'aucune requête n'échoue en préproduction :

Changement dans PostgreSQL 19 Ce qu'il faut vérifier
Passage de la valeur par défaut de max_locks_per_transaction de 64 à 128, et les réglages existants doivent être doublés Valeurs personnalisées dans votre configuration ou le groupe de paramètres de votre service managé
JIT désactivé par défaut Endpoints analytiques qui comptaient sur le JIT pour les requêtes longues
Compression TOAST par défaut passée de pglz à lz4 Rien ne casse, mais les profils de stockage et de CPU évoluent
standard_conforming_strings forcé à on Les anciens dumps réalisés avec off ne se restaureront pas
L'authentification par mot de passe MD5 journalise un avertissement ; RADIUS supprimé Migrer les rôles applicatifs vers SCRAM-SHA-256
json_array() sur zéro ligne renvoie [] Clients qui testent null
READ ONLY transmis à postgres_fdw Transactions en lecture seule qui écrivaient via une table distante
log_lock_waits activé par défaut Volume de journaux et bruit d'alertes

La mise à niveau depuis toute version majeure antérieure nécessite toujours pg_upgrade, un dump et une restauration via pg_dumpall, ou la réplication logique. Planifiez la migration dès maintenant si vous êtes sur PostgreSQL 14 : selon la politique de gestion des versions, sa dernière version est sortie le 12 novembre 2026.

Laissez votre agent de codage tester la régression de votre API après la mise à niveau avec Apidog CLI

Une mise à niveau majeure de Postgres casse rarement la syntaxe SQL. Elle casse les comportements : un json_array() qui renvoie [], une limite de verrous, un plan plus lent. Détectez-les en exécutant les scénarios de test de votre API sur une base de données PostgreSQL 19 en préproduction, en vérifiant à la fois la réponse HTTP et les lignes sous-jacentes. Laissez votre agent de codage le faire avec Apidog CLI.

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Ensuite, donnez à votre agent une seule invite :

In Apidog project <projectId>, add a test case for POST /users that sends the same
email twice and asserts the first call returns 201 and the second returns 200 with the
same id. Then run test scenario <scenarioId> against the pg19-staging environment with
database assertions, and summarize every failure next to the PostgreSQL 19 change
that could explain it.

L'agent lit le schéma du payload, le valide, crée le cas de test, puis exécute le scénario avec votre fichier de connexion à la base de données afin que les étapes base de données ciblent le nouveau cluster :

apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run -t <scenarioId> --project <projectId> -e <envId> \
  --database-connection ./database-connections.json -r cli,junit

Les opérations de base de données d'Apidog prennent en charge PostgreSQL sur le plan gratuit (Free), ce qui vous permet d'interroger la table après chaque requête et de vérifier que l'endpoint get-or-create a écrit exactement une ligne. La documentation explique les requêtes de base de données dans les tests d'API et l'exécution de scénarios avec des connexions de base de données depuis le CLI. Intégrez la même commande apidog run ... -r junit dans votre pipeline CI et chaque future version mineure bénéficiera de la même vérification. Si vous préférez laisser votre agent interroger Postgres directement, consultez le guide du serveur MCP PostgreSQL.

FAQ

Quand PostgreSQL 19 est-il sorti ? Le 19 novembre 2026. Le projet PostgreSQL maintient chaque version majeure pendant 5 ans, donc la version 19 recevra des correctifs jusqu'au 19 novembre 2031.

ON CONFLICT DO SELECT est-il équivalent à un upsert ? Non. DO UPDATE modifie la ligne existante ; DO SELECT la renvoie intacte. Utilisez-le pour le get-or-create et les POST idempotents. Il nécessite une clause RETURNING et une cible de conflit.

WAIT FOR LSN fonctionne-t-il sur le primaire ? Le mode par défaut standby_replay ne fonctionne que sur un standby en cours de récupération. Sur un primaire, vous obtenez une erreur, ou not in recovery avec NO_THROW. Utilisez MODE 'primary_flush' si vous devez attendre sur le primaire lui-même.

Peut-on passer de PostgreSQL 18 à 19 sans migration complète ? Oui, avec pg_upgrade. Vous pouvez aussi effectuer un dump/restauration ou utiliser la réplication logique, qui réplique désormais les séquences avec FOR ALL SEQUENCES. Consultez d'abord le tableau des changements incompatibles ci-dessus.

PostgreSQL 19 remplace-t-il pg_repack ? Dans la plupart des cas, oui. REPACK (CONCURRENTLY) récupère l'espace perdu et réorganise les tables par index sans bloquer les lectures ni les écritures, et il est intégré au cœur du système.

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API