Prisma createMany: too many bind variables en PostgreSQL

Vas a insertar miles de filas con createMany en una sola operación (por ejemplo, al cerrar un inventario se crea una fila por cada producto "faltante") y te preocupa que PostgreSQL lo rechace. Cuando una consulta de Prisma supera el tope de parámetros se ha reportado un mensaje como este:

too many bind variables in prepared statement, expected maximum of 32767, received 32768

Antes de añadir código para dividir los datos, conviene saber de dónde sale ese límite y qué hace ya Prisma. Este artículo lo explica con el código del motor de Prisma 6 y una prueba local con SQLite, y deja claro cuándo dividir en lotes sigue siendo útil, aunque por una razón distinta: controlar el tamaño de la transacción, no evitar el límite.

Por qué pasa

Prisma envía los valores de cada consulta como parámetros enlazados (bind) separados del texto SQL. En el protocolo de PostgreSQL, el mensaje Bind incluye un contador con el número de valores de parámetros, y ese campo es un entero de 16 bits (Int16 en la documentación del protocolo). Por eso una sola sentencia no puede llevar un número ilimitado de parámetros.

Verás dos cifras según dónde mires. El servidor de PostgreSQL lee ese contador de 2 bytes con una función que devuelve un entero sin signo, lo que da un máximo teórico de 65535. Pero Prisma trabaja con un tope más conservador para PostgreSQL: en el código de su motor (versión 6.19.0) el valor por defecto es 32766, y el mensaje de error habla de 32767. Para tu cálculo práctico, usa el de Prisma.

Un createMany de N filas con C columnas por fila genera N × C parámetros si se envía como un único INSERT. Por ejemplo, 2276 filas con 15 columnas son 34140 parámetros, por encima de 32766. Ese es el riesgo que lleva a muchos a dividir los datos a mano.

Lo que Prisma 6 ya hace por ti

En el código del motor, la generación de los INSERT de un createMany reparte las filas en lotes y abre un lote nuevo cuando la suma de parámetros superaría el máximo permitido del conector (max_bind_values). Los valores por defecto del motor son: PostgreSQL 32766, MySQL 65535, SQLite 999 y SQL Server 2098 (este último además limita a 1000 filas por INSERT).

Se comprobó con una prueba local en SQLite (Prisma 6.19.3). Con el registro de consultas activado, un createMany de 2500 filas de 3 columnas (7500 parámetros) produjo ocho INSERT (siete de 999 parámetros y uno de 507), dentro de un BEGIN y un COMMIT únicos. La documentación de Prisma indica además que createMany se ejecuta como una transacción. No se reprodujo con PostgreSQL (requiere un servicio en ejecución que aquí no se usó), así que para ese motor la conclusión se apoya en el código del motor, no en una ejecución.

Entonces, para un createMany simple en Prisma 6 no necesitas dividir los datos para esquivar el límite. Dónde sí puede aparecer el error: filtros con listas enormes (where: { id: { in: ids } }), donde se ha reportado que Prisma divide la lista pero no siempre bien en combinaciones con otros criterios, y el SQL crudo, que no pasa por esa lógica de reparto de createMany. Tampoco se verificó el comportamiento en Prisma 7 ni con adaptadores de controlador.

Solución

  1. Observa qué envía Prisma antes de cambiar nada. Activa el registro de consultas y ejecuta la carga:

    const prisma = new PrismaClient({ log: ['query'] });

    Si ves varias sentencias INSERT en lugar de una gigante, el motor ya está dividiendo.

  2. Si solo necesitas insertar muchas filas, una llamada basta. Es atómica por sí sola:

    await prisma.lineaInventario.createMany({ data: faltantes });
  3. Si quieres controlar el tamaño de cada paso, divide tú. Hay razones legítimas: no mantener todas las filas en memoria, registrar el progreso o decidir cuántas filas escribe cada sentencia. Un helper pequeño y genérico:

    // src/chunk.ts
    export function chunk<T>(items: readonly T[], size: number): T[][] {
      if (!Number.isInteger(size) || size < 1) {
        throw new RangeError('size debe ser un entero positivo');
      }
      const lotes: T[][] = [];
      for (let i = 0; i < items.length; i += size) {
        lotes.push(items.slice(i, i + size));
      }
      return lotes;
    }

    Úsalo de forma secuencial, dentro de la misma transacción si necesitas todo o nada:

    import { chunk } from './chunk';
    
    const TAMANO_LOTE = 1000;
    
    await prisma.$transaction(
      async (tx) => {
        for (const lote of chunk(faltantes, TAMANO_LOTE)) {
          await tx.lineaInventario.createMany({ data: lote });
        }
      },
      { timeout: 30_000 },
    );

    Ojo con el tiempo: las transacciones interactivas de Prisma tienen por defecto un timeout de 5000 ms (y maxWait de 2000 ms), después de los cuales se cancelan y se revierten. Con miles de filas conviene subirlo explícitamente, como arriba. En la prueba local, 2276 filas en lotes de 1000 se insertaron en una sola transacción sin errores, y el motor volvió a dividir cada lote cuando superaba el tope de SQLite; con PostgreSQL se midieron del orden de 2 segundos para esa misma cantidad, una cifra orientativa que depende de la red, las columnas y los índices.

  4. Elige la atomicidad conscientemente. Dividir en lotes dentro de una transacción no la acorta: sigue durando lo mismo y retiene sus bloqueos hasta el final. Si prefieres transacciones cortas, haz una por lote:

    for (const lote of chunk(faltantes, TAMANO_LOTE)) {
      await prisma.lineaInventario.createMany({ data: lote, skipDuplicates: true });
    }

    Así cada lote se confirma por separado. A cambio, si algo falla a mitad, queda una carga parcial: es necesario que repetir la operación sea seguro. skipDuplicates (no está disponible en todos los motores, por ejemplo MongoDB y SQL Server) ayuda cuando la tabla tiene una clave única que identifica cada fila; la documentación de Prisma indica que omite los registros que ya existen. La documentación también recomienda mantener las transacciones lo más cortas posible.

  5. Elige el tamaño del lote con una cuenta simple. Mantén filas × columnas por debajo del tope con margen. Para 15 columnas, 1000 filas son 15000 parámetros, bastante por debajo de 32766. Si tus filas son anchas (decenas de columnas), baja el lote: por ejemplo, Math.floor(30000 / columnas).

  6. Divide a mano lo que Prisma no divide. Para listas grandes en un in o para SQL crudo, procesa los identificadores por lotes:

    const encontrados = [];
    for (const ids of chunk(todosLosIds, 5000)) {
      encontrados.push(...(await prisma.producto.findMany({ where: { id: { in: ids } } })));
    }

Cómo verificar que quedó resuelto

  1. Cuenta las filas después de la carga y compáralas con las esperadas (await prisma.lineaInventario.count()).
  2. Con log: ['query'], comprueba que ninguna sentencia INSERT supere el tope de parámetros de tu motor.
  3. Provoca un fallo a propósito (por ejemplo, una fila con un valor inválido en el último lote) y confirma el comportamiento esperado: con una sola transacción no debe quedar ninguna fila nueva; con una transacción por lote, quedan los lotes anteriores.
  4. Mide el tiempo con tus datos reales. Las cifras de otro entorno no son comparables.

Variantes y errores relacionados

createManyAndReturn

En el código del motor, la variante que devuelve los registros usa la misma generación de sentencias que createMany, por lo que se reparte igual.

P2028: Transaction already closed

Si una carga grande dentro de $transaction supera el timeout, la transacción se cancela. Sube el valor o parte la carga en transacciones por lote.

Otros motores

SQLite (999 parámetros) y SQL Server (2098 parámetros y 1000 filas por INSERT) tienen topes mucho menores; por eso un mismo createMany genera más sentencias en ellos. El comportamiento es automático, pero tenlo presente al estimar tiempos.

Resumen

  • El límite viene del protocolo de PostgreSQL (contador de 16 bits en el mensaje Bind); Prisma trabaja con un tope de 32766 parámetros por sentencia en PostgreSQL.
  • En Prisma 6, createMany ya divide las filas en varias sentencias dentro de una misma transacción; no necesitas chunk() para esquivar el límite.
  • Divide a mano para controlar memoria, progreso y tamaño de la transacción, y para operaciones que Prisma no reparte (listas in enormes, SQL crudo).
  • Dividir dentro de una transacción no la acorta: ajusta timeout, o usa una transacción por lote asumiendo una carga parcial si falla.

Referencias

Comentarios