ElectricSQL: Sync local para Postgres

# Qué es ElectricSQL y qué problema resuelve en PostgreSQL

La sincronización de datos entre el servidor y el cliente sigue siendo uno de los desafíos técnicos más costosos en el desarrollo de software moderno. Construir una solución propia suele desembocar en capas complejas de WebSockets, gestión manual de caché y resolución de conflictos propensa a inconsistencias.

ElectricSQL aborda este problema posicionándose como una capa de sincronización desacoplada frente a una base de datos PostgreSQL estándar. Su propósito no es sustituir el motor relacional ni obligar a adoptar un modelo de datos propietario, sino resolver tres aspectos críticos:

• Replicación parcial (shapes): Permite que los clientes consuman únicamente los subconjuntos de datos relacionales que necesitan para su vista actual.
• Distribución de datos (fan-out): Gestiona la propagación masiva de cambios hacia múltiples clientes concurrentes sin sobrecargar la base de datos principal.
• Entrega local y en tiempo real: Mantiene los datos sincronizados en segundo plano en el dispositivo del usuario, habilitando patrones de arquitectura local-first.

Así como aplicaciones de referencia como Figma o Linear basan su fluidez en mantener un estado reactivo local en lugar de esperar una respuesta de red para cada interacción, ElectricSQL traslada este paradigma a las aplicaciones respaldadas por PostgreSQL, evitando que el equipo tenga que programar un motor de replicación desde cero.

---

# Posicionamiento frente a alternativas y desarrollo a medida

En el ecosistema actual existen dos extremos habituales: los servicios Backend-as-a-Service (BaaS) propietarios —como algunas implementaciones simplificadas que podemos encontrar en PocketBase— y los motores de sincronización desarrollados a mano.

La ventaja de ElectricSQL radica en respetar el esquema y las garantías transaccionales de PostgreSQL. No exige migrar a un motor documental ni delegar la capa de datos en una plataforma externa sujeta a cambios de precios o cuotas por uso de eventos.

---

# Flujo de configuración y consumo práctico

La arquitectura básica de ElectricSQL requiere dos piezas principales en el backend: una instancia de PostgreSQL con replicación lógica habilitada y el servicio de ElectricSQL conectado mediante una variable de entorno DATABASE_URL.

# 1. Entorno de ejecución con Docker

Para desarrollo local, el flujo habitual parte de un archivo de Docker Compose que levanta PostgreSQL y ElectricSQL en paralelo:

docker compose -f .support/docker-compose.yml up

En la configuración del entorno (.env), se definen los parámetros de conexión hacia ambas capas:

DATABASE_URL=postgresql://postgres:password@localhost:5432/my_database
ELECTRIC_URL=http://localhost:3000

# 2. Definición de Shapes y lectura de datos

El concepto central de ElectricSQL es el de shape (forma), que representa una consulta o tabla expuesta a través de su API HTTP. Los clientes pueden consumir directamente estas formas para replicar datos hacia el frontend.

En entornos React, la integración suele resolverse mediante hooks o bibliotecas de estado local como TanStack DB:

import { useShape } from '@electric-sql/react';

function TaskList() {
  const { data: tasks } = useShape({
    url: 'http://localhost:3000/v1/shape/foo',
  });

  return (
    <ul>
      {tasks.map((task) => (
        <li key={task.id}>{task.title}</li>
      ))}
    </ul>
  );
}

# 3. Mutaciones optimistas y proxy de autenticación

Para producción, el cliente no suele conectarse directamente al puerto expuesto de ElectricSQL sin control de acceso. El flujo recomendado intercala rutas en el servidor backend que actúan como proxy para filtrar y validar los shapes según la sesión del usuario.

A nivel de mutaciones, la persistencia local permite aplicar cambios de manera inmediata con reversión automática en caso de error:

const AddTodo = () => {
  return (
    <Button
      onClick={() =>
        todoCollection.insert({
          id: crypto.randomUUID(),
          text: 'Optimizar flujo de datos',
          completed: false,
        })
      }
    />
  );
};

Este esquema asegura que la interfaz no sufra latencia perceptiva, conciliando el identificador local con la confirmación de la base de datos principal de manera asíncrona.

---

# Escenarios de uso: dónde brilla y cuándo evitarlo

Un ejemplo de implementación real es SolidType, una herramienta de diseño paramétrico CAD que utiliza ElectricSQL junto con TanStack DB para sincronizar proyectos, documentos y metadatos de sesiones jerárquicas en segundo plano. En este tipo de software, donde la interacción visual requiere respuesta instantánea, desacoplar el renderizado del viaje de ida y vuelta a la red resulta fundamental.

# Cuándo tiene sentido adoptarlo

• Herramientas de productividad y edición: Editores de documentos, paneles de control colaborativos o software de diseño que exigen interactividad constante.
• Entornos con conectividad inestable: Aplicaciones móviles o de escritorio que deben seguir funcionando sin conexión y sincronizar cambios cuando se restablece el acceso a la red.
• Sistemas con estructuras relacionales complejas: Proyectos que ya dependen de consultas SQL, claves foráneas y restricciones relacionales que un BaaS tradicional maneja con dificultad.

# Cuándo no es recomendable

• Sitios web centrados en contenido estático o lectura pura: Blogs, catálogos públicos o portales informativos donde el almacenamiento en caché perimetral (CDN) resuelve el rendimiento con menor fricción operativa.
• Canales de escritura intensiva sin lectura inmediata: Sistemas de telemetría o ingesta de eventos continuos en los que la interfaz del usuario no requiere ver el reflejo local de cada inserción.
• Prototipos mínimos sin requerimiento de tiempo real: Si un formulario convencional responde en menos de 200 ms y la concurrencia es baja, habilitar replicación lógica y un servicio intermedio añade una sobrecarga de infraestructura difícil de justificar.

---

# Balance técnico y puntos de partida

ElectricSQL ofrece una vía estructurada para construir aplicaciones reactivas sin abandonar PostgreSQL. Al transformar la replicación lógica en un flujo HTTP de deltas comprensible para el navegador, traslada el esfuerzo de diseño desde la red hacia la definición de modelos locales.

A mi juicio, la principal barrera no reside en el código del cliente, sino en los requisitos operativos. La necesidad de administrar la replicación lógica, gestionar slots en PostgreSQL y proteger los shapes detrás de un proxy autenticado exige una disciplina de arquitectura superior a la de un API REST habitual.

Para evaluar la herramienta en un entorno controlado, el repositorio oficial incluye plantillas completas de inicio rápido, como el ejemplo tanstack-db-web-starter, que permite desplegar el contenedor de ElectricSQL junto a PostgreSQL y probar mutaciones optimistas en minutos.

# Referencias

• GitHub - electric-sql/electric: The agent platform built on sync.
• GitHub - samwillis/solidtype: A parametric CAD application built on ElectricSQL, Tanstack DB and Durable Streams · GitHub
• electric/examples/tanstack-db-web-starter/README.md at main · electric-sql/electric · GitHub