Doble clic ejecuta dos veces la operación: advisory lock

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.

  1. 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_lock obtiene 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 $executeRaw porque no hay filas que leer. La segunda petición queda esperando en la primera sentencia; cuando la primera confirma, obtiene el lock, relee y encuentra ACTIVE.

    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.

  2. 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.

  3. Prefiere una clave de 64 bits calculada en la aplicación. hashtext es una función interna de PostgreSQL: existe en el catálogo y aparece en el ejemplo de la clase de operadores del módulo bloom, 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 clave bigint o dos enteros de 32 bits, y son espacios de claves distintos. Con un identificador de texto, puedes derivar un bigint estable:

    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.

  4. Decide cuánto estás dispuesto a esperar. El tiempo que la segunda petición espera cuenta contra el timeout de la transacción interactiva de Prisma (5 segundos por defecto); si se agota, aparece P2028. 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 LOCAL vale solo hasta el final de la transacción. La documentación de lock_timeout habla 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 SQLSTATE 55P03 (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 es pg_try_advisory_xact_lock, que devuelve false sin 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 OperationInProgressError como 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 $transaction de 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_lock al 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 clave bigint en la aplicación.
  • Prueba con dos llamadas simultáneas contra PostgreSQL real; los mocks en secuencia no prueban la concurrencia.

Referencias

Comentarios