¿Qué es UPSERT (INSERT ON CONFLICT)?

Question

Accepted Answer

**UPSERT** significa "insertar, o actualizar si ya existe". PostgreSQL implementa esto con **`INSERT ... ON CONFLICT`** — inserta una fila, pero si violaría una restricción única, en su lugar actualiza la fila existente (o no hace nada). Maneja la necesidad común de "insertar-o-actualizar" de forma atómica.

## Por qué es importante

```text
You want to insert a row, but it might already exist (by a unique key):
  ❌ a plain INSERT fails with a unique-violation error if it exists
  ❌ check-then-insert (SELECT, then INSERT or UPDATE) has a RACE CONDITION
     (another transaction could insert between your check and insert)
→ ON CONFLICT does it atomically in ONE statement (no race condition)
```

## ON CONFLICT DO UPDATE — insertar o actualizar

```sql
INSERT INTO users (email, name, login_count)
VALUES ('ann@x.com', 'Ann', 1)
ON CONFLICT (email)                  -- if a row with this email already exists...
DO UPDATE SET                        -- ...UPDATE it instead
  name = EXCLUDED.name,              -- EXCLUDED = the values you tried to insert
  login_count = users.login_count + 1;  -- can reference the existing row too
```

Si insertar entraría en conflicto con la restricción única `email`, Postgres actualiza la fila existente en su lugar. **`EXCLUDED`** se refiere a los valores que intentaste insertar, y también puedes referenciar la fila existente (`users.login_count`) — habilitando lógica como incrementar un contador.

## ON CONFLICT DO NOTHING — insertar o saltar

```sql
INSERT INTO users (email, name) VALUES ('ann@x.com', 'Ann')
ON CONFLICT (email) DO NOTHING;      -- if it exists, just skip (no error)
```

`DO NOTHING` salta silenciosamente las filas en conflicto — útil para "insertar si no está presente" sin errores.

## Un uso común en la práctica: contadores e inserciones idempotentes

```sql
-- track page views — insert on first view, increment on subsequent
INSERT INTO page_views (page_id, views) VALUES (5, 1)
ON CONFLICT (page_id) DO UPDATE SET views = page_views.views + 1;
```

## Por qué es importante

UPSERT (`INSERT ... ON CONFLICT`) es una característica importante y prácticamente valiosa de PostgreSQL que resuelve de forma limpia la necesidad muy común de "insertar-o-actualizar", y de forma **segura**, por lo que comprenderla es útil para operaciones de datos del mundo real.

La necesidad — insertar una fila que podría ya existir (por una clave única) — surge constantemente (upserting de registros, contadores, inserciones idempotentes, sincronización de datos), y las alternativas ingenuas son problemáticas: un INSERT simple falla con un error si la fila existe, y el enfoque "revisar-luego-insertar" (SELECT luego INSERT-o-UPDATE) tiene una **condición de carrera** (otra transacción concurrente podría insertar entre tu revisión e inserción, causando errores o pérdida de actualizaciones). `ON CONFLICT` resuelve esto **atómicamente en una sola sentencia** — eliminando la condición de carrera, que es su beneficio clave de corrección para aplicaciones concurrentes.

Comprender ambas formas — **`DO UPDATE`** (insertar o actualizar, con `EXCLUDED` referenciando los valores intentados y la capacidad de referenciar la fila existente para lógica como incrementar contadores) y **`DO NOTHING`** (insertar o saltar silenciosamente) — cubre los patrones comunes (upserting de registros, inserciones idempotentes, mantenimiento de contadores/agregados).

Ya que insertar-o-actualizar es una operación frecuente y hacerlo correcta y seguramente (atómicamente, sin condiciones de carrera) importa para la integridad de datos en aplicaciones concurrentes, comprender UPSERT — qué resuelve, el beneficio de atomicidad/condición de carrera, y las formas DO UPDATE/DO NOTHING — es conocimiento PostgreSQL valioso y frecuentemente aplicado que proporciona una solución limpia y segura a una necesidad común que de otro modo es propensa a errores, convirtiéndola en una característica práctica e importante para aplicaciones reales.