PGlite: PostgreSQL en WASM para apps locales sin servidor

# Introducción y contexto

Muchos intentos anteriores por llevar bases de datos relacionales robustas al navegador o a entornos de ejecución puramente locales terminaron chocando contra muros de complejidad innecesaria. Intentar empaquetar una distribución completa de Linux dentro de WebAssembly solo para arrancar un demonio de base de datos suele generar binarios gigantescos, un consumo de memoria desproporcionado y una experiencia de desarrollo frustrante. El resultado general de esos experimentos fue un rendimiento pobre y una adopción marginal por parte de los desarrolladores indie.

Frente a ese panorama de soluciones sobredimensionadas, PGlite adopta una ruta completamente distinta. En lugar de virtualizar un sistema operativo entero, compila directamente el motor de PostgreSQL a WebAssembly, permitiendo ejecutar SQL real directamente en JavaScript sin servidores, contenedores Docker ni cuentas de usuario.

# Qué es PGlite y su arquitectura

Desarrollado por ElectricSQL, PGlite es una compilación de PostgreSQL optimizada para WebAssembly. De hecho, es parte de un ecosistema más amplio donde ElectricSQL permite sincronizar Postgres en tiempo real para habilitar arquitecturas local-first. A diferencia de proyectos previos que dependían de máquinas virtuales Linux en el navegador, este enfoque reduce drásticamente la fricción al operar de manera nativa en el entorno de ejecución de JavaScript.

PostgreSQL normalmente utiliza un modelo basado en la bifurcación de procesos (process forking), donde cada cliente nuevo que se conecta genera un proceso independiente para gestionar su sesión. Sin embargo, los programas compilados con Emscripten —el compilador de C a WebAssembly— no pueden crear nuevos procesos y operan estrictamente en un modo de proceso único.

Para resolver esta limitación, PGlite aprovecha el "modo de usuario único" (single user mode) que PostgreSQL incluye originalmente para tareas de recuperación y arranque desde la línea de comandos. Sobre esta base, introduce una ruta de entrada y salida adaptada para interactuar con el entorno JavaScript, permitiendo consultas reactivas y en tiempo real sin requerir una arquitectura de red tradicional.

# Uso práctico y flujo de integración

La instalación y el uso de PGlite siguen los patrones habituales de cualquier paquete moderno de Node.js o del ecosistema frontend. Se puede integrar mediante el gestor de paquetes de preferencia y configurarlo para almacenar los datos utilizando IndexedDB en el navegador o sistemas de archivos locales en Node.

En proyectos avanzados como gbrain, PGlite se utiliza a través de un motor adaptado (PGLiteEngine) que implementa la misma interfaz que un motor de PostgreSQL tradicional. Esto permite que herramientas complejas funcionen de manera totalmente embebida.

import { PGlite } from '@electric-sql/pglite';

// Inicializar una instancia de Postgres en memoria o almacenamiento local
const db = new PGlite('idb://mi-base-de-datos');

// Ejecutar una consulta SQL estándar
const resultado = await db.query('SELECT * FROM usuarios WHERE activo = true;');
console.log(resultado.rows);

La configuración requiere tener en cuenta las restricciones inherentes del entorno WASM. Por ejemplo, al utilizar extensiones pesadas como pgvector para bases de datos vectoriales, es necesario ajustar parámetros de configuración interna para evitar desbordamientos de memoria:

const db = new PGlite({
  dataDir: 'idb://vector-db',
  // Ajustes recomendados para entornos con límites de memoria en WASM
  extensions: ['vector']
});

# Escenarios de uso y limitaciones

Este enfoque resulta especialmente útil para ciertas arquitecturas modernas:

• Aplicaciones con arquitectura local-first que necesitan persistencia relacional robusta sin depender de una conexión constante a la nube.
• Herramientas de línea de comandos (CLI) o agentes de inteligencia artificial locales que requieren almacenamiento estructurado sin obligar al usuario final a instalar Docker o configurar bases de datos externas.
• Entornos de prueba y desarrollo rápido donde levantar un servidor de base de datos ralentiza el flujo de trabajo.

Por otro lado, existen limitaciones claras que deben considerarse. PGlite en WASM limita típicamente su memoria a un máximo de 2 GiB. Operaciones masivas de indexación, como la construcción de grafos HNSW grandes con pgvector, pueden consumir gran cantidad de memoria en maintenance_work_mem, lo que obliga a configurar parámetros específicos como max_parallel_maintenance_workers=0 ya que no existen procesos de trabajadores paralelos.

# Conclusión y perspectivas

Personalmente, considero que eliminar la necesidad de Docker para proyectos pequeños o herramientas locales representa un avance significativo en la experiencia de desarrollo. PGlite demuestra que no siempre es necesario replicar arquitecturas de servidores distribuidos cuando el entorno cliente tiene la potencia suficiente para ejecutar el motor de forma aislada.

Para el desarrollador indie o el creador de herramientas de código abierto, representa una alternativa sólida para construir software independiente, rápido y con cero fricción de configuración inicial.

# Referencias

• GitHub - electric-sql/pglite: Embeddable Postgres with real-time, reactive bindings.
• gbrain/docs/ENGINES.md at master · garrytan/gbrain · GitHub
• ebrain/docs/ENGINES.md at master · woosal1337/ebrain · GitHub