En una aplicación multiempresa, cada empresa numera sus documentos desde 1 (DOC-2026-00001). Las empresas existentes funcionan, pero al crear el primer documento de una empresa nueva falla este error:
PrismaClientKnownRequestError:
Unique constraint failed on the fields: (`documentNumber`)
code: 'P2002'
El mensaje exacto varía con la versión de Prisma y la base de datos; el código es P2002. Este artículo explica por qué una restricción única global es incompatible con una numeración por empresa, cómo cambiarla a una restricción compuesta y cómo calcular el siguiente número sin count(). Aplica a Prisma 6 con PostgreSQL.
Por qué pasa
El esquema declara el número como único en toda la tabla, mientras que la secuencia se calcula por empresa con count():
model Document {
id String @id @default(cuid())
companyId String
year Int
sequence Int
documentNumber String @unique // único en TODAS las empresas
}
const count = await prisma.document.count({ where: { companyId, year } })
const sequence = count + 1
const documentNumber = `DOC-${year}-${String(sequence).padStart(5, '0')}`
La empresa A ya tiene DOC-2026-00001. La empresa B, sin documentos, obtiene count = 0, calcula sequence = 1 y genera el mismo texto. El índice único global lo rechaza. La regla de negocio ("único por empresa") y la restricción de la base de datos ("único en toda la tabla") no coinciden.
Hay un segundo defecto latente: count() supone que no se borra nada. Si una empresa tiene los documentos 1, 2 y 3 y se elimina el 2, el siguiente cálculo da count + 1 = 3, un número que ya existe. Eso fallaría incluso con la restricción corregida.
Solución
-
Cambia la unicidad global por una compuesta. La documentación de Prisma define
@@uniquepara exigir que la combinación de varios campos sea única:model Document { id String @id @default(cuid()) companyId String year Int sequence Int documentNumber String @@unique([companyId, documentNumber]) @@unique([companyId, year, sequence]) }Genera la migración con
npx prisma migrate dev --name numero-unico-por-empresa. El SQL resultante solo toca índices (con el esquema anterior y este,prisma migrate diffproduce exactamente esto):-- DropIndex DROP INDEX "Document_documentNumber_key"; -- CreateIndex CREATE UNIQUE INDEX "Document_companyId_documentNumber_key" ON "Document"("companyId", "documentNumber"); -- CreateIndex CREATE UNIQUE INDEX "Document_companyId_year_sequence_key" ON "Document"("companyId", "year", "sequence");El índice sobre
companyIdydocumentNumberno puede fallar con datos existentes: el anterior era más estricto, así que cualquier tabla que lo cumpla cumple también el nuevo. El decompanyId,yearysequencesí es una regla nueva y fallaría si ya hay duplicados. Compruébalo antes de migrar; la consulta no debe devolver filas:SELECT "companyId", "year", "sequence", count(*) FROM "Document" GROUP BY 1, 2, 3 HAVING count(*) > 1;Un
CREATE INDEXnormal bloquea las escrituras de la tabla mientras se construye (las lecturas siguen); en tablas grandes, aplica la migración en un momento de poca actividad.En el cliente, el selector único pasa a ser el par:
findUnique({ where: { companyId_documentNumber: { companyId, documentNumber } } }). Las consultas antiguas conwhere: { documentNumber }dejan de compilar en TypeScript, lo que ayuda a localizarlas. -
Deriva el siguiente número del último de la empresa en ese año, no de
count(). Usa una columna entera (sequence) en lugar de interpretar el texto, que además puede ordenarse mal si alguna vez cambió el ancho de los ceros:const { _max } = await tx.document.aggregate({ where: { companyId, year }, _max: { sequence: true }, }) const sequence = (_max.sequence ?? 0) + 1Si hoy solo guardas el texto, añade primero la columna entera y rellénala a partir de él, como en cualquier migración de datos.
-
Reintenta una vez ante
P2002, en una transacción nueva. Dos peticiones simultáneas de la misma empresa pueden calcular el mismo valor; el índice compuesto rechaza la segunda. Al repetir, el cálculo ya ve el número confirmado por la primera:import { Prisma, PrismaClient } from '@prisma/client' const prisma = new PrismaClient() function isUniqueViolation(e: unknown): e is Prisma.PrismaClientKnownRequestError { return e instanceof Prisma.PrismaClientKnownRequestError && e.code === 'P2002' } export async function createDocument(companyId: string, year: number) { for (let attempt = 1; attempt <= 2; attempt++) { try { return await prisma.$transaction(async (tx) => { const { _max } = await tx.document.aggregate({ where: { companyId, year }, _max: { sequence: true }, }) const sequence = (_max.sequence ?? 0) + 1 return tx.document.create({ data: { companyId, year, sequence, documentNumber: `DOC-${year}-${String(sequence).padStart(5, '0')}`, }, }) }) } catch (e) { if (attempt === 2 || !isUniqueViolation(e)) throw e } } throw new Error('Inalcanzable') }El reintento envuelve la transacción completa porque, en PostgreSQL, tras un error dentro de una transacción las siguientes sentencias se rechazan (
25P02,in_failed_sql_transaction) hasta revertirla. Si el modelo tiene otras restricciones únicas, compruebae.meta?.targetpara reintentar solo cuando el choque es del número. La documentación de Prisma muestrametacon la forma{ target: ['email'] }, pero la forma exacta depende de la versión y del conector: regístrala antes de comparar. -
Con mucha concurrencia, serializa en lugar de reintentar. Un único reintento no basta si llegan tres o más peticiones a la vez para la misma empresa. Puedes tomar al inicio de la transacción un advisory lock por empresa y año (
pg_advisory_xact_lock) para que se ejecuten una tras otra. El índice único sigue siendo la garantía final; el lock evita los reintentos.
Cómo verificar que quedó resuelto
- Ejecuta
npx prisma migrate status: debe indicar que el esquema está al día. - En
psql,\d "Document"debe listar los índices únicos compuestos y ya no el dedocumentNumbersolo. - Crea el primer documento de una empresa nueva mientras otra ya tiene
…00001: ambas deben tener su propio…00001. - Borra un documento intermedio y crea otro: debe continuar desde el máximo, no repetir un número existente.
- Lanza dos
createDocumenta la vez para la misma empresa conPromise.allSettled: ambas deben tener éxito con números distintos y consecutivos. Este test necesita una base de datos PostgreSQL real; con mocks no hay concurrencia.
Variantes y errores relacionados
El mismo P2002 por otra causa
Un P2002 también aparece si dos peticiones insertan el mismo registro a la vez, o si otro campo único (un correo, un código) se repite. Revisa los campos que indica el mensaje antes de tocar el esquema.
Unicidad global y datos entre empresas
Además de bloquear la numeración, una restricción global hace que el error de una empresa revele que otra ya usa ese valor. Cuando el dato pertenece a cada empresa, la restricción debe incluir companyId.
Documentos eliminados
Si usas borrado lógico, los números de los documentos "eliminados" siguen ocupando su lugar en el índice y en el máximo. Es lo habitual en la numeración, pero conviene saberlo.
Por qué no count()
count() solo coincide con el último número mientras no haya borrados ni huecos. El máximo de una columna entera funciona en ambos casos.
Resumen
- Un
@uniqueglobal es incompatible con una secuencia por empresa: el primer número de la empresa B choca con el de la A. - Cambia a
@@unique([companyId, ...]); la migración solo elimina y crea índices y es segura con los datos actuales. - Calcula el siguiente número con el máximo de la empresa y año, no con
count(), que falla con borrados. - Reintenta una vez ante
P2002en una transacción nueva, o serializa con un lock si hay mucha concurrencia. - Prueba con una base de datos real: una empresa nueva, un borrado y dos creaciones simultáneas.
Comentarios
Publicar un comentario