Exportación en streaming de grandes tablas de Postgres a CSV en Node.js y FastifyArtículo · digest del 7 de noviembre
Corte visual del pipeline de exportación en streaming de datos desde PostgreSQL a CSV mediante Fastify con paginación Keyset y un consumo estable de 66 MB de memoria.
Artículo4 secciones≈ 9 min

Exportación en streaming de grandes tablas de Postgres a CSV en Node.js y Fastify

Todo desarrollador backend se enfrenta tarde o temprano a una petición de negocio aparentemente inofensiva: «Haz un botón para "Exportar todos los pedidos a Excel"». Abres el proyecto, escribes el manejador, haces SELECT * FROM orders, serializas el array de objetos resultante en filas separadas por comas y lo envías al cliente. En tu máquina local con una base de 500 filas todo vuela.

Pero pasa medio año, el proyecto crece y la tabla acumula 350 mil registros. Un gestor pulsa el botón de exportación, tres segundos después otro gestor repite la acción y el servidor de aplicaciones cae de golpe con el error fatal JavaScript heap out of memory.

En el entorno Node.js con el motor V8, almacenar en búfer grandes consultas en memoria de forma ingenua es una bomba de relojería garantizada. Cada fila de la base de datos se convierte en un objeto con clases ocultas (hidden classes) de V8, para la conversión se crean millones de búferes de cadenas intermedios y el recolector de basura (GC) entra en bloqueo.

En un detallado estudio práctico de saprahan en Habr, el ingeniero desglosó una arquitectura industrial de streaming de datos desde PostgreSQL a CSV usando el framework Fastify, el query builder Knex.js y generadores asíncronos.

Veamos esta mecánica paso a paso: cómo construir un pipeline de extremo a extremo sin guardado intermedio en disco, sortear la trampa de los microsegundos y mantener un consumo de memoria constante.

Por qué un SELECT ingenuo mata la memoria de Node.js

Para dimensionar el problema basta con mirar las mediciones reales de consumo de recursos. En el entorno de pruebas se exportaba una tabla típica de 347,000 filas (el archivo CSV resultante pesa alrededor de 37 megabytes):

  • Método ingenuo (todas las filas a la memoria del proceso): La consulta terminó rápido, en 2.0 segundos. Pero el pico de consumo del heap (heapUsed) se disparó hasta 576 MB, y el tamaño total del proceso (RSS) superó los 833 MB. Con el límite por defecto del heap de Node.js en 1.4 GB, dos exportaciones simultáneas tumban con seguridad el pod o el proceso por OOM.
  • Método en streaming con paginación OFFSET: El consumo del heap cayó a unos estables 86 MB, pero el tiempo de ejecución se multiplicó por 7 hasta alcanzar 14.5 segundos.

¿Por qué el clásico LIMIT 1000 OFFSET 200000 funciona tan lento? Porque una base de datos relacional no sabe saltar a un punto arbitrario del disco por número de fila. Para entregar mil filas con un offset de 200 mil, el planificador de PostgreSQL está obligado a leer físicamente del disco 200,000 filas, descartarlas y solo entonces devolver el lote necesario. La complejidad de esa consulta es $O(OFFSET + LIMIT)$. En cada página siguiente el servidor de base de datos desperdicia cada vez más tiempo de CPU.

Paginación Keyset frente a OFFSET: benchmarks y la trampa de los microsegundos

La única forma de exportar datos rápido y ligero es usar paginación Keyset (paginación por cursor). En lugar de contar desplazamientos, nos apoyamos en un índice B-tree compuesto sobre los campos de ordenación, como ya comentamos en el artículo sobre matices de optimización en PostgreSQL:

CREATE INDEX CONCURRENTLY idx_orders_created_at_id ON orders ("createdAt" DESC, id DESC);

Cada lote siguiente se solicita mediante comparación de tuplas: (createdAt, id) < (cursorCreatedAt, cursorId). La base encuentra al instante el punto exacto en el índice con complejidad $O(\log N)$.

En el benchmark sobre las mismas 347,000 filas, la combinación de streaming y paginación Keyset dio un resultado fenomenal:

  • Tiempo de ejecución: apenas 2.8 segundos (prácticamente igual que el método ingenuo en memoria);
  • Pico de heapUsed: solo 66 MB (¡9 veces menos!);
  • Pico de RSS: 173 MB.

Pero aquí acecha a los desarrolladores la trampa más traicionera de la plataforma, donde es muy fácil perder datos.

En el objeto Date de JavaScript el tiempo se almacena en milisegundos (3 decimales). En cambio, en PostgreSQL el tipo timestamptz almacena microsegundos (6 decimales). Cuando el driver pg parsea automáticamente la fecha de la base a un objeto JS, los microsegundos se truncan de forma irreversible.

Si en un mismo milisegundo se crearon varios registros, el cursor truncado en la siguiente consulta filtrará las filas con la misma hora pero con microsegundos menores. ¡Como resultado desaparecerán sin dejar rastro decenas de filas de la exportación!

La solución es elegante: extraer el timestamp de la base estrictamente como texto sin procesar records."createdAt"::text as "cursorTs" y pasarlo de vuelta al SQL con conversión explícita de tipo (?::timestamptz, ?).

Streaming de extremo a extremo con Fastify, contrapresión y compatibilidad con Excel

El archivo CSV en sí no se guarda en el servidor ni un segundo. Construimos el pipeline mediante un stream nativo Readable:

import { Readable } from 'node:stream';
import { Knex } from 'knex';

const CHUNK_SIZE = 2000;
const DELIMITER = ';';
const UTF8_BOM = '\uFEFF';
const COLUMNS = ['id', 'email', 'status', 'createdAt'];

function escapeCsv(val: any): string {
  if (val == null) return '';
  const str = val instanceof Date ? val.toISOString() : String(val);
  return /[";\r\n]/.test(str) ? `"${str.replace(/"/g, '""')}"` : str;
}

export async function* generateOrdersCsv(db: Knex) {
  // Añadimos UTF-8 BOM y cabecera con punto y coma como separador para Excel
  yield UTF8_BOM + COLUMNS.join(DELIMITER) + '\r\n';

  let cursor: { createdAt: string; id: number } | null = null;

  for (;;) {
    const query = db('orders')
      .select('orders.*', db.raw('orders."createdAt"::text as "cursorTs"'))
      .orderBy('createdAt', 'desc')
      .orderBy('id', 'desc')
      .limit(CHUNK_SIZE);

    if (cursor) {
      query.whereRaw('(orders."createdAt", orders.id) < (?::timestamptz, ?)', [
        cursor.createdAt,
        cursor.id,
      ]);
    }

    const chunk = await query;
    if (!chunk.length) break;

    for (const row of chunk) {
      const line = COLUMNS.map((col) => escapeCsv(row[col])).join(DELIMITER);
      yield line + '\r\n';
    }

    const last = chunk[chunk.length - 1];
    cursor = { createdAt: last.cursorTs, id: last.id };
  }
}

Fíjate en tres detalles críticos para la compatibilidad con Microsoft Excel:

  1. \uFEFF (Byte Order Mark) justo al inicio del flujo indica a Excel que el archivo está codificado en UTF-8, evitando caracteres ilegibles en lugar de letras acentuadas o cirílicas.
  2. El separador ; (punto y coma) en lugar de coma es el estándar en muchas configuraciones regionales de Excel.
  3. Los saltos de línea estrictamente \r\n (CRLF).

Protección de la conexión, cancelación del cliente y tokens temporales de descarga

El framework Fastify entiende de forma nativa los streams de Node.js. Cuando llamas a reply.send(Readable.from(generator)), Fastify conecta por sí mismo el stream al socket HTTP, establece la cabecera Transfer-Encoding: chunked y activa el mecanismo de contrapresión (backpressure). Si el usuario tiene una conexión móvil lenta, el stream pausa automáticamente la generación de lotes desde la base de datos sin inflar la memoria.

Pero ¿qué pasa si el usuario cierra la pestaña a los diez segundos de iniciar la descarga? Si no se gestiona el corte de conexión, el generador asíncrono seguirá leyendo millones de filas de la base hacia la nada.

Además, la descarga en el navegador mediante enlace directo no sabe enviar la cabecera Authorization: Bearer. La solución consiste en generar un token JWT firmado de un solo uso con 5 minutos de vida:

import Fastify, { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
import { Readable } from 'node:stream';
import jwt from 'jsonwebtoken';
import { generateOrdersCsv } from './orders-export';

export function setupExportRoutes(app: FastifyInstance, db: any, secret: string) {
  app.get('/api/orders/export', async (req: FastifyRequest<{ Querystring: { token: string } }>, reply: FastifyReply) => {
    const { token } = req.query;
    if (!token) return reply.code(401).send({ error: 'Se requiere token' });

    try {
      const payload: any = jwt.verify(token, secret);
      if (payload.scope !== 'orders-csv') throw new Error('Scope inválido');
    } catch {
      return reply.code(403).send({ error: 'Token inválido o caducado' });
    }

    const filename = `orders-${new Date().toISOString().slice(0, 10)}.csv`;
    reply.header('Content-Disposition', `attachment; filename="${filename}"`);
    reply.type('text/csv; charset=utf-8');

    const generator = generateOrdersCsv(db);
    const stream = Readable.from(generator);

    // Si el cliente corta la conexión, detenemos el generador liberando la base
    reply.raw.on('close', () => {
      if (!reply.raw.writableEnded) {
        stream.destroy();
      }
    });

    return reply.send(stream);
  });
}

Esta arquitectura hace que la exportación sea indestructible: el servidor mantiene unos estables 60 megabytes de memoria RAM ante cualquier volumen de datos, Excel abre el archivo a la perfección y los clientes lentos o las desconexiones no generan fugas de conexiones en el pool de PostgreSQL.

Quiero un análisis detalladoLos votos ayudan a elegir qué analizar a fondo. Este material tiene 0 votos.
Fuentes · 3