SQL Academy · Lección

UPSERT: ON CONFLICT DO UPDATE (PostgreSQL)

Implemente inserciones idempotentes con ON CONFLICT DO UPDATE, use EXCLUDED y elija el objetivo de conflicto adecuado.

UPSERT: ON CONFLICT DO UPDATE (PostgreSQL) es una lección gratuita de SQL Academy en CoddyKit. Esta es la lección 2 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de SQL Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de SQL Academy incluye 4 lecciones en total.

¿Qué es UPSERT?

UPSERT = INSERT si no existe y UPDATE si existe. PostgreSQL lo expresa como INSERT ... ON CONFLICT.

ON CONFLICT DO NOTHING

Inserte si falta y omita silenciosamente la fila si está duplicada:

INSERT INTO users (email, full_name)
VALUES ('alice@example.com', 'Alice')
ON CONFLICT (email) DO NOTHING;

ON CONFLICT DO UPDATE

Inserte si falta; de lo contrario, actualice columnas específicas:

INSERT INTO users (email, full_name, last_login)
VALUES ('alice@example.com', 'Alice', NOW())
ON CONFLICT (email)
DO UPDATE SET
  full_name  = EXCLUDED.full_name,
  last_login = EXCLUDED.last_login;

EXCLUDED: la fila propuesta

Dentro de DO UPDATE, EXCLUDED.col significa "el valor que INSERT intentó insertar". El nombre de columna sin calificar (o users.col) se refiere a la fila existente.

ON CONFLICT (email)
DO UPDATE SET visits = users.visits + 1,
              last_seen = EXCLUDED.last_seen;

El objetivo del conflicto

Debe indicar una restricción UNIQUE o una clave primaria:

ON CONFLICT (email)             -- column with UNIQUE
ON CONFLICT (user_id, day)      -- composite UNIQUE
ON CONFLICT ON CONSTRAINT users_email_key   -- by name

UPSERT condicional (WHERE en DO UPDATE)

Actualice únicamente cuando se cumpla una condición:

INSERT INTO inventory (product_id, qty)
VALUES (42, 5)
ON CONFLICT (product_id)
DO UPDATE SET qty = inventory.qty + EXCLUDED.qty
WHERE inventory.qty + EXCLUDED.qty <= 1000;

UPSERT de varias filas

Inserte muchas filas; cada una se procesa por separado:

INSERT INTO page_views (path, day, count)
VALUES ('/home', CURRENT_DATE, 1), ('/about', CURRENT_DATE, 1)
ON CONFLICT (path, day)
DO UPDATE SET count = page_views.count + EXCLUDED.count;

RETURNING con UPSERT

Recupere la fila resultante, tanto si se insertó como si se actualizó:

INSERT INTO users (email, full_name)
VALUES ('alice@example.com', 'Alice')
ON CONFLICT (email) DO UPDATE
  SET full_name = EXCLUDED.full_name
RETURNING id, full_name;

Flujos de trabajo idempotentes

UPSERT hace que los reintentos sean seguros. Si su webhook se ejecuta dos veces, la segunda llamada actualiza la misma fila en lugar de duplicarla.

MERGE (estándar SQL, PG15+)

PostgreSQL 15 añadió MERGE, una instrucción del estándar SQL que puede ejecutar INSERT, UPDATE y DELETE en una sola instrucción:

MERGE INTO users AS u
USING (VALUES ('alice@example.com','Alice')) AS src(email, name)
ON u.email = src.email
WHEN MATCHED THEN UPDATE SET full_name = src.name
WHEN NOT MATCHED THEN INSERT (email, full_name) VALUES (src.email, src.name);

Cuándo no usar UPSERT

UPSERT requiere una restricción UNIQUE. Si no dispone de una, normalmente querrá realizar un SELECT separado y luego un INSERT o UPDATE; pero tenga cuidado con las condiciones de carrera: use una transacción con el bloqueo adecuado.

Resumen

ON CONFLICT es el UPSERT limpio y atómico de PostgreSQL.

DO NOTHING para "insertar si no existe"
DO UPDATE para un upsert real
EXCLUDED = la fila propuesta
Indique siempre un objetivo del conflicto

Comprobación rápida

En ON CONFLICT (email) DO UPDATE SET last_login = EXCLUDED.last_login, ¿a qué se refiere EXCLUDED?

Preguntas frecuentes

¿La lección «UPSERT: ON CONFLICT DO UPDATE (PostgreSQL)» es gratis?

Sí — el texto completo de «UPSERT: ON CONFLICT DO UPDATE (PostgreSQL)» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de SQL Academy, actualiza a CoddyKit PRO. El curso de SQL Academy incluye 4 lecciones en total.

¿Qué aprenderé en «UPSERT: ON CONFLICT DO UPDATE (PostgreSQL)»?

Implemente inserciones idempotentes con ON CONFLICT DO UPDATE, use EXCLUDED y elija el objetivo de conflicto adecuado. Practicas SQL Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar SQL Academy?

No se requiere experiencia previa. SQL Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 2 de 4.

¿Cuánto tiempo toma la lección «UPSERT: ON CONFLICT DO UPDATE (PostgreSQL)»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de SQL Academy?

Sí. Cada lección de SQL Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

INSERT con varias filas
UPSERT: ON CONFLICT DO UPDATE (PostgreSQL)
UPDATE con FROM y actualizaciones al estilo JOIN
DELETE con USING y patrones seguros

← Volver a SQL Academy