Troubleshooting

Tips and answers to FAQs about how to run Electric successfully.

Local development

Slow shapes — why are my shapes slow in the browser in local development?

Sometimes people encounter a mysterious slow-down with Electric in local development, when your web app is subscribed to 6 or more shapes. This slow-down is caused by a limitation of the legacy version of HTTP, 1.1.

With HTTP/1.1, browsers only allow 6 simultaneous requests to a specific backend. This is because each HTTP/1.1 request uses its own expensive TCP connection. As shapes are loaded over HTTP, this means only 6 shapes can be getting updates with HTTP/1.1 due to this browser restriction. All other requests pause until there's an opening.

Luckily, HTTP/2, introduced in 2015, fixes this problem by multiplexing each request to a server over the same TCP connection. This allows essentially unlimited connections. HTTP/2 is standard across the vast majority of hosts now. Unfortunately it's not yet standard in local dev environments.

Solution — run Caddy

To fix this, you can setup a local reverse-proxy using the popular Caddy server. Caddy automatically sets up HTTP/2 and proxies requests to Electric, getting around the 6 requests limitation with HTTP/1.1 in the browser.

This command runs Caddy so it's listening on port 3001 and proxying shape requests to Electric which listens on port 3000. If you're loading shapes through your API or framework dev server, replace 3000 with the port that your API or dev server is listening on.

npx @radically-straightforward/caddy run \
    --config - \
    --adapter caddyfile \
    <<EOF
:3001 {
  reverse_proxy localhost:3000
  encode {
    gzip
  }
}
EOF

Now change your shape URLs to use port 3001 instead of port 3000 and everything will run much faster 🚀

Clear data — how do I clear the server state?

Electric creates resources, including a logical replication publication and replication slots in your Postgres database. Electric also stores shape logs to disk.

Sometimes in development you may want to clear this state. However, just restarting the services doesn't clear the underlying storage. This can lead to unexpected data in your database or shape logs.

Solution — clear the storage volumes

If you're running using Docker Compose, the simplest solution is to bring the Postgres and Electric services down, using the --volumes flag to also clear their mounted storage volumes:

docker compose down --volumes

You can then bring a fresh backend up from scratch:

docker compose up

Production

WAL growth — why is my Postgres database storage filling up?

Electric creates a logical replication publication in your Postgres database and adds tables dynamically (as you request shapes) to this publication.

If you don't consume this publication, the WAL can fill up and your Postgres database can run out of storage space. A common way for this to happen is that you create an Electric publication and then stop running Electric.

Solution — run Electric

The simplest way to avoid this is to make sure you're running the Electric sync service against Postgres. This will consume the publication and allow the WAL to be released.