Installation

You need to have a Postgres database and to run the Electric sync service in front of it.

How to run Electric

Electric is a web application published as a Docker image at electricsql/electric. It connects to Postgres via a DATABASE_URL.

Recommended

The simplest way to run Electric is using Docker.

Using Docker

You can run a fresh Postgres and Electric connected together using Docker Compose with this docker-compose.yaml:

version: "3.3"
name: "electric_quickstart"

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: electric
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    ports:
      - 54321:5432
    tmpfs:
      - /var/lib/postgresql/data
      - /tmp
    command:
      - -c
      - listen_addresses=*
      - -c
      - wal_level=logical

  electric:
    image: electricsql/electric
    environment:
      DATABASE_URL: postgresql://postgres:password@postgres:5432/electric?sslmode=disable
    ports:
      - "3000:3000"
    depends_on:
      - postgres

For example you can run this using:

curl -O https://electric-sql.com/docker-compose.yaml
docker compose up

Alternatively, you can run the Electric sync service on its own and connect it to an existing Postgres database, e.g.:

docker run \
    -e "DATABASE_URL=postgresql://..." \
    -p 3000:3000 \
    -t \
    electricsql/electric:latest

Postgres requirements

You can use any Postgres (new or existing) that has logical replication enabled. You also need to connect as a database user that has the REPLICATION role.

Advanced

You can also choose to build and run Electric from source as an Elixir application.

Build from source

Clone the Electric repo:

git clone https://github.com/electric-sql/electric.git
cd electric

Install the system dependencies with asdf. Versions are defined in .tool-versions:

asdf plugin-add elixir
asdf plugin-add erlang
asdf plugin-add nodejs
asdf plugin-add pnpm
asdf install

Install the packages/sync-service dependencies using Mix.:

cd packages/sync-service
mix deps.get

Run the development server:

mix run --no-halt

This will try to connect to Postgres using the DATABASE_URL configured in packages/sync-service/.env.dev, which defaults to:

LOG_LEVEL=debug
DATABASE_URL=postgresql://postgres:password@localhost:54321/electric?sslmode=disable
ELECTRIC_ENABLE_INTEGRATION_TESTING=true
ELECTRIC_CACHE_MAX_AGE=1
ELECTRIC_CACHE_STALE_AGE=3
# using a small chunk size of 10kB for dev to speed up tests
ELECTRIC_LOG_CHUNK_BYTES_THRESHOLD=10000
ELECTRIC_DATABASE_ID=test_tenant
# configuring a second database for multi-tenancy integration testing
OTHER_DATABASE_URL=postgresql://postgres:password@localhost:54322/electric?sslmode=disable

You can edit this file to change the configuration. To run the tests, you'll need a Postgres running that matches the :test env config in config/runtime.exs and then:

mix test

If you need any help, ask on Discord.