Las nuevas funciones de PostgreSQL 19 que más importan a los desarrolladores de API: INSERT ... ON CONFLICT DO SELECT para endpoints de get-or-create en una sola instrucción, WAIT FOR LSN para read-your-writes en réplicas, REPACK (CONCURRENTLY) para limpiar la fragmentación en línea, salida JSON desde COPY, nuevos métodos de cadena en jsonpath y verificaciones de claves foráneas más rápidas en inserciones masivas.

Prueba Apidog hoy

Esta guía cubre qué cambia en tus handlers, réplicas y plan de actualización. Todos los ejemplos de sintaxis provienen de las notas de la versión de PostgreSQL 19 y sus páginas de referencia.

Novedades de PostgreSQL 19 de un vistazo

PostgreSQL 19 es la versión mayor anual de la base de datos de código abierto, anunciada por el PostgreSQL Global Development Group el 19 de noviembre de 2026. Añade inserciones get-or-create, esperas en réplicas para read-your-writes, repackado de tablas en línea, consejos de plan y replicación lógica de secuencias, y cambia varios valores predeterminados que debes revisar antes de actualizar.

Función Qué reemplaza Dónde la notarás
ON CONFLICT DO SELECT Bucles de reintento con SELECT seguido de INSERT Endpoints POST idempotentes y de registro
WAIT FOR LSN Enrutamiento fijo de lecturas al primario Réplicas de lectura detrás de una API
REPACK (CONCURRENTLY) VACUUM FULL, CLUSTER, pg_repack Tablas calientes fragmentadas, sin tiempo de inactividad
COPY ... (FORMAT json) Conversión de filas a JSON en código de aplicación Endpoints de exportación y descarga masiva
jsonpath métodos de cadena Postprocesado de JSONB en código de aplicación Filtrado y normalización de columnas JSON
pg_plan_advice + pg_stash_advice Reescribir consultas para guiar al planificador Regresiones de plan en producción
Publicaciones FOR ALL SEQUENCES Restablecimientos manuales de secuencias tras el cutover Actualizaciones blue-green mediante replicación lógica

El anuncio oficial de la versión también menciona el vacuumado paralelo de índices y trabajadores de E/S asíncrona con escalado automático. Estos no cambian el SQL que envía tu API, así que esta entrada no los cubre.

ON CONFLICT DO SELECT: get-or-create en una sola instrucción

Toda API tiene un endpoint que debe devolver una fila exista o no: registrar un dispositivo, crear una etiqueta, iniciar un checkout idempotente. Antes de la versión 19 ejecutabas un SELECT y luego un INSERT (y perdías las condiciones de carrera bajo carga), o escribías un ON CONFLICT DO UPDATE ficticio solo para que RETURNING se activara, lo que escribe una nueva versión de fila para nada.

PostgreSQL 19 añade una cuarta acción de conflicto. La referencia de INSERT la describe como un «insert idempotente u obtener o crear»:

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

Si did = 11 está libre, la fila se inserta y se devuelve. Si ya está ocupada, se devuelve la fila existente y no se modifica nada. Tres reglas de la documentación:

  • Se requiere una cláusula RETURNING con DO SELECT.
  • Se requiere un conflict_target, igual que con DO UPDATE.
  • Las restricciones de exclusión no pueden actuar como árbitros; usa un índice único o una restricción única NOT DEFERRABLE.

Diagrama de flujo de una petición POST /users que usa INSERT ON CONFLICT (email) DO SELECT RETURNING

Tu handler normalmente necesita saber qué rama se ejecutó, para poder responder con 201 Created o 200 OK. La documentación señala que los valores antiguos de RETURNING no son NULL cuando hubo conflicto con la fila, así que una sola columna te lo indica:

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

¿Necesitas bloquear la fila existente antes de tocar tablas relacionadas? Añade una cláusula de bloqueo: ON CONFLICT (did) DO SELECT FOR UPDATE RETURNING *. También puedes filtrar con WHERE, por ejemplo DO SELECT WHERE d.dname != EXCLUDED.dname, y solo se devolverán las filas que cumplan la condición.

Privilegios: DO SELECT necesita SELECT sobre la tabla, y las formas FOR UPDATE/FOR SHARE también necesitan UPDATE sobre al menos una columna.

WAIT FOR LSN: read-your-writes en réplicas

El clásico bug de las réplicas: un usuario guarda su perfil, la siguiente petición GET llega a una réplica asíncrona que aún no ha replicado el cambio, y se devuelven datos obsoletos. La mayoría de los equipos fijan las lecturas al primario después de una escritura, lo que desperdicia la réplica.

PostgreSQL 19 añade el comando WAIT FOR. Tras una escritura, obtén la posición WAL del primario:

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

Guarda ese LSN en la sesión del usuario (Simon Willison sugiere una cookie firmada en su artículo). En la siguiente petición, ejecuta esto en la réplica antes de la lectura:

WAIT FOR LSN '0/0306EE20' WITH (TIMEOUT '100ms', NO_THROW); SELECT * FROM movie WHERE genre = 'Drama'; 

Diagrama de secuencia con WAIT FOR LSN en la réplica de lectura

Los detalles que importan en una API:

  1. Modos. El modo predeterminado MODE 'standby_replay' espera hasta que el cambio se haya aplicado, que es lo que necesita read-your-writes. standby_write, standby_flush y primary_flush existen para comprobaciones de durabilidad.
  2. Timeouts. Sin TIMEOUT, o con TIMEOUT '0', espera indefinidamente. Establece siempre uno en las rutas de petición.
  3. NO_THROW. Sin él, un timeout lanza un error y aborta tu transacción. Con él, obtienes un estado de success, timeout o not in recovery, y puedes recurrir al primario.
  4. Ubicación. WAIT debe ser un comando de nivel superior, no dentro de una función o bloque DO. Ejecútalo fuera de una transacción o como su primera instrucción, antes de cualquier cosa que tome un bloqueo, o será rechazado.

REPACK (CONCURRENTLY) reemplaza a VACUUM FULL en tablas activas

Las tablas detrás de endpoints con mucho tráfico, como sessions o webhook_deliveries, se fragmentan rápido. VACUUM FULL y CLUSTER lo solucionan, pero bloquean la tabla. PostgreSQL 19 añade una opción en línea:

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

Las notas de la versión indican que REPACK (CONCURRENTLY) recupera espacio y puede reordenar una tabla por un índice sin bloquear lecturas ni escrituras. VACUUM FULL y CLUSTER se mantienen por compatibilidad. Sigue el progreso en la nueva vista pg_stat_progress_repack y busca la nueva opción de servidor max_repack_replication_slots cuando ajustes el clúster.

Salida JSON desde COPY y nuevos métodos de cadena en jsonpath

Los endpoints de exportación a menudo transmiten filas a través del código de aplicación solo para convertirlas en JSON. COPY TO ahora puede hacerlo en la base de datos, según la referencia de COPY:

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

Esto imprime [, {"id":1}, ,{"id":2} y ] en líneas separadas, de modo que la salida es un único array JSON válido. Sin FORCE_ARRAY obtienes un objeto JSON por línea, lo cual es compatible con NDJSON. Los valores NULL de SQL se convierten en null de JSON, y el formato json solo funciona con COPY TO.

Para columnas JSONB, jsonpath incorpora métodos de cadena: lower(), upper(), initcap(), ltrim(), rtrim(), btrim(), replace() y split_part(). La documentación muestra:

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

Las notas de la versión las marcan como inmutables, y te permiten normalizar un campo JSONB (recortarlo, pasarlo a minúsculas, dividirlo) dentro de la consulta en lugar de en tu handler.

Además, json_array() sobre cero filas ahora devuelve [] en lugar de NULL, lo que puede romper un cliente que comprueba si el valor es null.

Otros cambios de PostgreSQL 19 que los equipos de API deberían conocer

  • Verificaciones de claves foráneas más rápidas. El anuncio indica que lograron inserciones masivas casi 2 veces más rápidas en pruebas. Útil para endpoints de importación que escriben filas hijas.
  • Consejos de plan. La extensión pg_plan_advice fija las decisiones del planificador, y pg_stash_advice aplica esos consejos por ID de consulta, así puedes corregir una consulta con regresión sin redeplegar.
  • UUID y codificación. Puedes hacer cast entre bytea y uuid, y encode()/decode() admiten base64url, el formato seguro para URLs de IDs en rutas y tokens.
  • Replicación lógica para actualizaciones. CREATE PUBLICATION all_sequences FOR ALL SEQUENCES; sincroniza secuencias, y FOR ALL TABLES EXCEPT (TABLE users, departments) excluye tablas. Esto cierra el hueco de «los IDs colisionan tras el cutover» en migraciones blue-green.

Cambios incompatibles que debes revisar antes de actualizar

La sección de migración de las notas de la versión enumera cambios que pueden afectar a una API sin que una sola consulta falle en staging:

Cambio en PostgreSQL 19 Qué revisar
max_locks_per_transaction pasa de 64 a 128 por defecto, y los valores existentes deben duplicarse Valores personalizados en tu configuración o en el grupo de parámetros del servicio gestionado
JIT deshabilitado por defecto Endpoints de analítica que dependían del JIT para consultas largas
Compresión TOAST por defecto cambia de pglz a lz4 Nada se rompe, pero los perfiles de almacenamiento y CPU cambian
standard_conforming_strings forzado a on Los volcados antiguos hechos con él en off no se restaurarán
La autenticación con contraseñas MD5 registra una advertencia; RADIUS eliminado Migra los roles de la aplicación a SCRAM-SHA-256
json_array() sobre cero filas devuelve [] Clientes que comprueban si el valor es null
READ ONLY se propaga a postgres_fdw Transacciones de solo lectura que escribían a través de una tabla foránea
log_lock_waits activado por defecto Volumen de logs y ruido de alertas

Actualizar desde cualquier versión mayor anterior sigue requiriendo pg_upgrade, un volcado y restauración con pg_dumpall, o replicación lógica. Planifica el cambio ahora si usas PostgreSQL 14: según la política de versiones, su versión final fue el 12 de noviembre de 2026.

Deja que tu agente de código haga pruebas de regresión a tu API tras la actualización con Apidog CLI

Una actualización mayor de Postgres rara vez rompe la sintaxis SQL. Rompe el comportamiento: un json_array() que devuelve [], un límite de bloqueos, un plan más lento. Detecta los problemas ejecutando los escenarios de prueba de tu API contra una base de datos PostgreSQL 19 en staging, con aserciones sobre la respuesta HTTP y las filas que hay detrás. Deja que tu agente de código lo haga con 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 

Luego dale a tu agente un solo prompt:

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. 

El agente lee el esquema del payload, lo valida, crea el caso y luego ejecuta el escenario con tu archivo de conexión a base de datos para que los pasos de base de datos apunten al nuevo clúster:

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 

Las operaciones de base de datos de Apidog admiten PostgreSQL en el plan gratuito, así que puedes consultar la tabla después de cada petición y verificar que el endpoint get-or-create escribió exactamente una fila. La documentación explica consultas de base de datos en pruebas de API y cómo ejecutar escenarios con conexiones de base de datos desde la CLI. Pon el mismo comando apidog run ... -r junit en tu pipeline de CI y cada versión menor posterior recibirá la misma comprobación. Si prefieres que tu agente consulte Postgres directamente, consulta la guía del servidor MCP de PostgreSQL.

Preguntas frecuentes

¿Cuándo se lanzó PostgreSQL 19? El 19 de noviembre de 2026. El proyecto PostgreSQL mantiene cada versión mayor durante 5 años, así que la versión 19 recibirá correcciones hasta el 19 de noviembre de 2031.

¿ON CONFLICT DO SELECT es lo mismo que un upsert? No. DO UPDATE modifica la fila existente; DO SELECT la devuelve sin tocar. Úsalo para get-or-create y POST idempotentes. Requiere una cláusula RETURNING y un objetivo de conflicto.

¿WAIT FOR LSN funciona en el primario? El modo predeterminado standby_replay solo funciona en un standby durante la recuperación. En un primario obtienes un error, o not in recovery con NO_THROW. Usa MODE 'primary_flush' si necesitas esperar en el propio primario.

¿Puedo actualizar de PostgreSQL 18 a 19 en el lugar? Sí, con pg_upgrade. También puedes hacer volcado y restauración, o usar replicación lógica, que ahora replica secuencias con FOR ALL SEQUENCES. Revisa primero la tabla de cambios incompatibles de arriba.

¿PostgreSQL 19 reemplaza a pg_repack? En la mayoría de los casos, sí. REPACK (CONCURRENTLY) recupera el espacio fragmentado y reordena tablas por índice sin bloquear lecturas ni escrituras, y viene incluido en el núcleo.