SurfSense/surfsense_web/content/docs/how-to/electric-sql.mdx

---
title: Electric SQL
description: Setting up Electric SQL for real-time data synchronization in SurfSense
---

[Electric SQL](https://electric-sql.com/) enables real-time data synchronization in SurfSense, providing instant updates for inbox items, document indexing status, and connector sync progress without manual refresh. The frontend uses [PGlite](https://pglite.dev/) (a lightweight PostgreSQL in the browser) to maintain a local database that syncs with the backend via Electric SQL.

## What Does Electric SQL Do?

When you index documents or receive inbox updates, Electric SQL pushes updates to your browser in real-time. The data flows like this:

1. Backend writes data to PostgreSQL
2. Electric SQL detects changes and streams them to the frontend
3. PGlite (running in your browser) receives and stores the data locally in IndexedDB
4. Your UI updates instantly without refreshing

This means:

- **Inbox updates appear instantly** - No need to refresh the page
- **Document indexing progress updates live** - Watch your documents get processed
- **Connector status syncs automatically** - See when connectors finish syncing
- **Offline support** - PGlite caches data locally, so previously loaded data remains accessible

## Docker Setup

The `docker-compose.yml` includes the Electric SQL service. It is pre-configured to connect to the Docker-managed `db` container out of the box.

```bash
docker compose up -d
```

The Electric SQL service configuration in `docker-compose.yml`:

```yaml
electric:
  image: electricsql/electric:1.4.6
  ports:
    - "${ELECTRIC_PORT:-5133}:3000"
  environment:
    DATABASE_URL: ${ELECTRIC_DATABASE_URL:-postgresql://${ELECTRIC_DB_USER:-electric}:${ELECTRIC_DB_PASSWORD:-electric_password}@${DB_HOST:-db}:${DB_PORT:-5432}/${DB_NAME:-surfsense}?sslmode=${DB_SSLMODE:-disable}}
    ELECTRIC_INSECURE: "true"
    ELECTRIC_WRITE_TO_PG_MODE: direct
  depends_on:
    db:
      condition: service_healthy
```

No additional configuration is required — Electric SQL is pre-configured to work with the Docker PostgreSQL instance.

## Manual Setup

Follow the steps below based on your PostgreSQL setup.

### Step 1: Configure Environment Variables

Ensure your environment files are configured. If you haven't set up SurfSense yet, follow the [Manual Installation Guide](/docs/manual-installation) first.

For Electric SQL, verify these variables are set in `docker/.env`:

```bash
ELECTRIC_PORT=5133
ELECTRIC_DB_USER=electric
ELECTRIC_DB_PASSWORD=electric_password
NEXT_PUBLIC_ELECTRIC_URL=http://localhost:5133
```

**Frontend (`surfsense_web/.env`):**

```bash
NEXT_PUBLIC_ELECTRIC_URL=http://localhost:5133
NEXT_PUBLIC_ELECTRIC_AUTH_MODE=insecure
```

---

### Option A: Using Docker PostgreSQL

If you're using the Docker-managed PostgreSQL instance, no extra configuration is needed. Just start the services:

```bash
docker compose up -d db electric
```

Then run the database migration and start the backend:

```bash
cd surfsense_backend
uv run alembic upgrade head
uv run main.py
```

Electric SQL is now configured and connected to your Docker PostgreSQL database.

---

### Option B: Using Local PostgreSQL

If you're using a local PostgreSQL installation (e.g. Postgres.app on macOS), follow these steps:

**1. Enable logical replication in PostgreSQL:**

Open your `postgresql.conf` file:

```bash
# Common locations:
# macOS (Postgres.app): ~/Library/Application Support/Postgres/var-17/postgresql.conf
# macOS (Homebrew):     /opt/homebrew/var/postgresql@17/postgresql.conf
# Linux:                /etc/postgresql/17/main/postgresql.conf

sudo vim /path/to/postgresql.conf
```

Add the following settings:

```ini
# Required for Electric SQL
wal_level = logical
max_replication_slots = 10
max_wal_senders = 10
```

After saving, restart PostgreSQL for the settings to take effect.

**2. Create the Electric replication user:**

Connect to your local database as a superuser and run:

```sql
CREATE USER electric WITH REPLICATION PASSWORD 'electric_password';
GRANT CONNECT ON DATABASE surfsense TO electric;
GRANT CREATE ON DATABASE surfsense TO electric;
GRANT USAGE ON SCHEMA public TO electric;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO electric;
GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO electric;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO electric;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON SEQUENCES TO electric;
CREATE PUBLICATION electric_publication_default;
```

**3. Set `ELECTRIC_DATABASE_URL` in `docker/.env`:**

Uncomment and update this line to point Electric at your local Postgres via `host.docker.internal` (the hostname Docker containers use to reach the host machine):

```bash
ELECTRIC_DATABASE_URL=postgresql://electric:electric_password@host.docker.internal:5432/surfsense?sslmode=disable
```

**4. Start Electric SQL only (skip the Docker `db` container):**

```bash
docker compose up -d --no-deps electric
```

The `--no-deps` flag starts only the `electric` service without starting the Docker-managed `db` container.

**5. Run database migration and start the backend:**

```bash
cd surfsense_backend
uv run alembic upgrade head
uv run main.py
```

Electric SQL is now configured and connected to your local PostgreSQL database.

## Environment Variables Reference

| Variable | Location | Description | Default |
|----------|----------|-------------|---------|
| `ELECTRIC_PORT` | `docker/.env` | Port to expose Electric SQL | `5133` |
| `ELECTRIC_DB_USER` | `docker/.env` | Database user for Electric replication | `electric` |
| `ELECTRIC_DB_PASSWORD` | `docker/.env` | Database password for Electric replication | `electric_password` |
| `ELECTRIC_DATABASE_URL` | `docker/.env` | Full connection URL override for Electric. Set to use `host.docker.internal` when pointing at a local Postgres instance | *(built from above defaults)* |
| `NEXT_PUBLIC_ELECTRIC_URL` | Frontend `.env` | Electric SQL server URL (PGlite connects to this) | `http://localhost:5133` |
| `NEXT_PUBLIC_ELECTRIC_AUTH_MODE` | Frontend `.env` | Authentication mode (`insecure` for dev, `secure` for production) | `insecure` |

## Verify Setup

To verify Electric SQL is running correctly:

```bash
curl http://localhost:5133/v1/health
```

You should receive:

```json
{"status":"active"}
```

## Troubleshooting

### Electric SQL Server Not Starting

**Check PostgreSQL settings:**
- Ensure `wal_level = logical` is set
- Verify the Electric user has replication permissions
- Check database connectivity from Electric container

### Real-time Updates Not Working

1. Open browser DevTools → Console
2. Look for errors containing `[Electric]`
3. Check Network tab for WebSocket connections to the Electric URL

### Connection Refused Errors

- Verify Electric SQL server is running: `docker ps | grep electric`
- Check the `NEXT_PUBLIC_ELECTRIC_URL` matches your Electric server address
- For Docker setups, ensure the frontend can reach the Electric container

### Data Not Syncing

- Check Electric SQL logs: `docker compose logs electric`
- Verify PostgreSQL replication is working
- Ensure the Electric user has proper table permissions

### PGlite/IndexedDB Issues

If data appears stale or corrupted in the browser:

1. Open browser DevTools → Application → IndexedDB
2. Delete databases starting with `surfsense-`
3. Refresh the page - PGlite will recreate the local database and resync