Un usuario hace doble clic en "Activar", o abre la misma pantalla en dos pestañas y pulsa el botón en ambas. No aparece ningún error, pero la base de datos queda con dos registros de auditoría y dos pagos para una única activación, y el saldo se sobrescribe con el valor de la segunda ejecución. El código parece correcto: valida el estado y todo ocurre dentro de una transacción de Prisma.
export async function activateCompany(companyId: string, planAmountCents: number) {
return prisma.$transaction(async (tx) => {
const company = await tx.company.findUnique({ where: { id: companyId } })
if (company?.status === 'ACTIVE') throw new Error('Ya está activa') // 1. comprobar
await tx.company.update({ // 2. actuar
where: { id: companyId },
data: { status: 'ACTIVE', balanceCents: planAmountCents },
})
await tx.payment.create({ data: { companyId, amountCents: planAmountCents } })
await tx.auditLog.create({ data: { companyId, action: 'COMPANY_ACTIVATED' } })
})
}
Este artículo explica por qué la transacción no basta y cómo serializar la operación con un advisory lock (bloqueo consultivo) de PostgreSQL, con las alternativas y sus compromisos. Se asume Prisma Client 6 y PostgreSQL con el nivel de aislamiento por defecto.
Por qué pasa
Es un fallo de tipo TOCTOU (time-of-check to time-of-use): se comprueba el estado en un instante y se actúa en otro, y entre ambos otra petición pudo hacer exactamente lo mismo. Una transacción garantiza que las escrituras se confirman o se revierten juntas, pero no impide que otra transacción lea el mismo estado "pendiente" al mismo tiempo.
La documentación de PostgreSQL describe el nivel por defecto, Read Committed: un SELECT ve solo los datos confirmados antes de que la consulta empezara. Si las dos peticiones leen antes de que alguna confirme, las dos ven PENDING, las dos superan la validación y las dos escriben. Prisma usa el nivel de aislamiento configurado en la base de datos, que en PostgreSQL es Read Committed.
Solución
La idea es que la segunda petición espere a que termine la primera y, solo entonces, vuelva a leer el estado.
-
Toma un lock transaccional por el identificador de negocio, antes de leer el estado.
export class CompanyNotFoundError extends Error {} export class AlreadyActiveError extends Error {} export async function activateCompany(companyId: string, planAmountCents: number) { return prisma.$transaction(async (tx) => { // 1. Serializar por empresa: la segunda llamada espera aquí await tx.$executeRaw`SELECT pg_advisory_xact_lock(hashtext(${companyId}))` // 2. Releer el estado DESPUÉS de obtener el lock const company = await tx.company.findUnique({ where: { id: companyId } }) if (!company) throw new CompanyNotFoundError(companyId) if (company.status === 'ACTIVE') throw new AlreadyActiveError(companyId) // 3. Efectos await tx.company.update({ where: { id: companyId }, data: { status: 'ACTIVE', balanceCents: planAmountCents }, }) await tx.payment.create({ data: { companyId, amountCents: planAmountCents } }) await tx.auditLog.create({ data: { companyId, action: 'COMPANY_ACTIVATED' } }) }) }Según la documentación,
pg_advisory_xact_lockobtiene un bloqueo exclusivo a nivel de transacción, esperando si hace falta, y se libera al terminar la transacción; no existe un desbloqueo manual. Es "consultivo": PostgreSQL no lo impone, solo funciona porque todo el código que ejecuta esta operación pide la misma clave. Se usa$executeRawporque no hay filas que leer. La segunda petición queda esperando en la primera sentencia; cuando la primera confirma, obtiene el lock, relee y encuentraACTIVE.Dos condiciones son críticas. La lectura debe ir después del lock. Y la transacción debe seguir en Read Committed: en Repeatable Read la instantánea se toma al empezar la primera sentencia de la transacción, que aquí es la propia sentencia del lock, así que la relectura posterior no vería lo que confirmó la otra petición. Si cambias
isolationLevel, este patrón deja de ser válido. -
Traduce el rechazo a un 409. El código HTTP 409 indica un conflicto con el estado actual del recurso, que es exactamente este caso:
try { await activateCompany(id, 5000) return Response.json({ ok: true }) } catch (error) { if (error instanceof AlreadyActiveError) { return Response.json({ error: 'La empresa ya está activa' }, { status: 409 }) } throw error }Si prefieres que el doble clic parezca un éxito, devuelve el resultado ya existente con un 200 en lugar de un 409: es la versión idempotente.
-
Prefiere una clave de 64 bits calculada en la aplicación.
hashtextes una función interna de PostgreSQL: existe en el catálogo y aparece en el ejemplo de la clase de operadores del módulobloom, pero no figura en la referencia de funciones de la documentación, así que nada garantiza que su resultado se mantenga entre versiones. Además devuelve solo 32 bits: dos identificadores distintos pueden producir la misma clave (solo causaría esperas innecesarias). La documentación admite una clavebiginto dos enteros de 32 bits, y son espacios de claves distintos. Con un identificador de texto, puedes derivar unbigintestable:import { createHash } from 'node:crypto' function advisoryKey(scope: string, id: string): bigint { const digest = createHash('sha256').update(`${scope}:${id}`).digest() return digest.readBigInt64BE(0) } // dentro de la transacción: const key = advisoryKey('activate-company', companyId) await tx.$executeRaw`SELECT pg_advisory_xact_lock(${key}::bigint)`El prefijo (
activate-company) separa operaciones distintas. Conviene porque las claves son compartidas en toda la base de datos y la propia herramienta de migraciones de Prisma también usa advisory locks. -
Decide cuánto estás dispuesto a esperar. El tiempo que la segunda petición espera cuenta contra el
timeoutde la transacción interactiva de Prisma (5 segundos por defecto); si se agota, apareceP2028. Para fallar antes y de forma controlada puedes limitar la espera de bloqueos solo en esa transacción:await tx.$executeRaw`SET LOCAL lock_timeout = '3s'`SET LOCALvale solo hasta el final de la transacción. La documentación delock_timeouthabla de cualquier espera por un bloqueo sobre una tabla, un índice, una fila u otro objeto; comprueba con tu test que también corta la espera del advisory lock. Si se supera, PostgreSQL responde con el código SQLSTATE55P03(lock_not_available); Prisma debería reportarlo como error de consulta cruda (P2010), pero verifica la forma exacta en tu versión. Otra opción espg_try_advisory_xact_lock, que devuelvefalsesin esperar y permite responder "operación en curso" al instante:const rows = await tx.$queryRaw<{ locked: boolean }[]>` SELECT pg_try_advisory_xact_lock(${key}::bigint) AS locked` if (!rows[0]?.locked) throw new OperationInProgressError(companyId)(Define
OperationInProgressErrorcomo las otras dos clases de error y tradúcelo también a un 409.)
Cómo verificar que quedó resuelto
Con un test de integración contra una base de datos PostgreSQL real. Lanza las dos llamadas a la vez y comprueba que solo una tiene éxito y que no hay efectos duplicados (el pool debe permitir al menos dos conexiones):
it('solo una de dos activaciones simultáneas tiene éxito', async () => {
const company = await prisma.company.create({ data: {} })
const results = await Promise.allSettled([
activateCompany(company.id, 5000),
activateCompany(company.id, 5000),
])
const rejected = results.filter((r): r is PromiseRejectedResult => r.status === 'rejected')
expect(results.filter((r) => r.status === 'fulfilled')).toHaveLength(1)
expect(rejected).toHaveLength(1)
expect(rejected[0].reason).toBeInstanceOf(AlreadyActiveError)
expect(await prisma.payment.count({ where: { companyId: company.id } })).toBe(1)
expect(await prisma.auditLog.count({ where: { companyId: company.id } })).toBe(1)
})
Una carrera es difícil de provocar con regularidad. Para comprobar que el test detecta el fallo, quita el lock en una copia y añade await tx.$executeRaw`SELECT pg_sleep(0.2)` entre la comprobación y la escritura: sin el lock el test debe fallar, con el lock debe pasar.
Un test unitario con mocks no sirve para esto. Llamar dos veces en secuencia a la función, con la base de datos simulada, demuestra la lógica ("si el estado ya es activo, lanza AlreadyActiveError"), pero no la concurrencia: las llamadas nunca se solapan y el lock ni siquiera se ejecuta. Es útil como complemento, no como prueba de que la carrera desapareció.
A mano, con dos sesiones de psql. En la sesión A ejecuta BEGIN; SELECT pg_advisory_xact_lock(42);. En la sesión B ejecuta lo mismo: se queda esperando. Desde una tercera sesión, SELECT pid, mode, granted FROM pg_locks WHERE locktype = 'advisory'; muestra un lock concedido y otro con granted = false. Al hacer COMMIT en A, B continúa.
Variantes y errores relacionados
Alternativa: UPDATE condicional
Si la operación es una transición de estado de una sola fila, es lo más simple y no necesita lock explícito:
const { count } = await tx.company.updateMany({
where: { id: companyId, status: 'PENDING' },
data: { status: 'ACTIVE', balanceCents: planAmountCents },
})
if (count === 0) throw new AlreadyActiveError(companyId)
En Read Committed, un segundo UPDATE sobre la misma fila espera a que la primera transacción termine y vuelve a evaluar el WHERE contra la versión actualizada, así que solo uno obtiene count = 1. Compromiso: count = 0 no distingue "ya activa" de "no existe" (hay que consultar después) y no sirve cuando la comprobación abarca varias filas o la ausencia de filas.
Alternativa: SELECT ... FOR UPDATE
Bloquea la fila antes de decidir. Prisma no lo ofrece en su API de modelos (existe una petición abierta), así que se usa SQL crudo con los nombres reales de tabla y columna:
const rows = await tx.$queryRaw<{ id: string; status: string }[]>`
SELECT id, status FROM "Company" WHERE id = ${companyId} FOR UPDATE`
Compromiso: pierdes el tipado del modelo y dependes de los nombres de la base de datos (por ejemplo, si usas @map). Requiere que exista la fila; con un advisory lock puedes serializar incluso cuando todavía no hay nada que bloquear.
Alternativa: restricción única o clave de idempotencia
Una tabla de activaciones con @@unique([companyId]), o una clave de idempotencia enviada por el cliente y guardada con el resultado, hace que el segundo intento falle con P2002 o devuelva el resultado anterior. Es la mejor opción para "solo una vez en la vida" o para reintentos de red, pero exige cambiar el esquema y, en el caso de la clave, decidir cuánto tiempo se conservan.
Deshabilitar el botón
Es una mejora de experiencia, no una garantía: no protege contra dos pestañas, reintentos del navegador o clientes de la API. Úsalo además del control en el servidor, nunca en su lugar.
Otros detalles
- Con un pooler de conexiones como PgBouncer en modo transacción, los advisory locks de sesión no están soportados; los de transacción se liberan al terminar la transacción y no dependen de la sesión.
- Una petición que espera el lock mantiene abierta su transacción y ocupa una conexión del pool; con mucha concurrencia sobre la misma clave, limita la espera como se explica arriba.
- Si una transacción toma más de un lock, hazlo siempre en el mismo orden para evitar bloqueos mutuos.
- La documentación más reciente de Prisma describe una API de transacciones distinta (Prisma ORM 8). Este artículo usa
$transactionde Prisma 6; la idea (lock, releer y validar dentro de la transacción) es la misma.
Resumen
- Una transacción no evita que dos peticiones lean el mismo estado antiguo: comprobar y luego actuar es una carrera.
- Toma
pg_advisory_xact_lockal empezar la transacción, relee el estado después y responde 409 si ya está hecho. - Funciona en Read Committed; en Repeatable Read la relectura no vería la confirmación de la otra petición.
- Evita
hashtext(interna, 32 bits) y calcula una clavebiginten la aplicación. - Prueba con dos llamadas simultáneas contra PostgreSQL real; los mocks en secuencia no prueban la concurrencia.
Comentarios
Publicar un comentario