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:

name: 'electric_quickstart'

services:
  postgres:
    image: docker.io/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
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 5s
      timeout: 5s
      retries: 5

  electric:
    image: docker.io/electricsql/electric:latest
    environment:
      DATABASE_URL: postgresql://postgres:password@postgres:5432/electric?sslmode=disable
      # Not suitable for production. Only use insecure mode in development or if you've otherwise secured the Electric API.
      # See https://electric-sql.com/docs/guides/security
      ELECTRIC_INSECURE: true
    ports:
      - '3000:3000'
    depends_on:
      postgres:
        condition: service_healthy

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.

See the PostgreSQL Permissions guide for detailed instructions on configuring database users with the necessary permissions for Electric.

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:

ELECTRIC_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_SHAPE_CHUNK_BYTES_THRESHOLD=10000
# configuring a second database for multi-tenancy integration testing
OTHER_DATABASE_URL=postgresql://postgres:password@localhost:54322/electric?sslmode=disable
ELECTRIC_PROFILE_WHERE_CLAUSES=false
ELECTRIC_OTEL_SAMPLING_RATIO=1
ELECTRIC_OTEL_DEBUG=false
ELECTRIC_INSECURE=true

ELECTRIC_TWEAKS_PROCESS_REGISTRY_PARTITIONS=1
ELECTRIC_TWEAKS_HTTP_API_NUM_ACCEPTORS=1

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.