Sync service

The Electric sync service is an Elixir application that manages active-active replication between your Postgres database and your local apps. This page documents all of the configuration options supported by the service.

The standard way to start Electric sync service is using the official Docker image which can be run either from the command line or via Docker Compose. In both cases, the configuration options are passed to the service as environment variables as in the following example:

docker run \
    -e "DATABASE_URL=postgresql://..." \
    -e "LOGICAL_PUBLISHER_HOST=..." \
    -e "AUTH_JWT_ALG=HS512" \
    -e "AUTH_JWT_KEY=..." \
    -p 5133:5133 \
    -p 5433:5433 \
    electricsql/electric

For detailed installation and running instructions see Usage -> Installation -> Sync service.

Configuration options

The Electric application is configured using environment variables.

Core config

Everything in the table below that doesn't have a default value is required to run the sync service.

Variable	Description
DATABASE_URL	PostgreSQL connection URL for the database.
DATABASE_REQUIRE_SSL   (false)	Set to yes or true to require SSL for the connection to the database. Alternatively configure SSL for the connection by adding sslmode=require to the DATABASE_URL parameters. Values set in the DATABASE_URL will have precedence.
LOGICAL_PUBLISHER_HOST	Host of this electric instance for the reverse connection from Postgres. It has to be accessible from the Postgres instance that is running at DATABASE_URL.
LOGICAL_PUBLISHER_PORT   (5433)	Port number to use for reverse connections from Postgres.
HTTP_PORT   (5133)	Port for HTTP connections. Includes client websocket connections on /ws, and other functions on /api

Authentication

When AUTH_MODE=secure (the default), the AUTH_JWT_ALG and AUTH_JWT_KEY options are also required.

When AUTH_MODE=insecure, all other authentication options can be omitted.

Variable	Description
AUTH_MODE   (secure)	Authentication mode to use to authenticate clients. Secure authentication is assumed by default and is strongly recommended for production use. The other option is Insecure authentication which should only be used in development.
AUTH_JWT_ALG	The algorithm to use for JWT verification. Electric supports the following algorithms: HS256, HS384, HS512: HMAC-based cryptographic signature that relies on the SHA-2 family of hash functions. RS256, RS384, RS512: RSA-based algorithms for digital signature. ES256, ES384, ES512: ECC-based algorithms for digital signature.
AUTH_JWT_KEY	The key to use for JWT verification. Must be appropriate for the chosen signature algorithm. For RS* and ES* algorithms, the key must be in PEM format.
AUTH_JWT_NAMESPACE	This is an optional setting that specifies the location inside the token of custom claims that are specific to Electric. Currently, only the user_id custom claim is required.
AUTH_JWT_ISS	This optional setting allows you to specificy the "issuer" that will be matched against the iss claim extracted from auth tokens. This can be used to ensure that only tokens created by the expected party are used to authenticate your client.
AUTH_JWT_AUD	This optional setting allows you to specificy the "audience" that will be matched against the aud claim extracted from auth tokens. This can be used to ensure that only tokens for a specific application are used to authenticate your client.

Telemetry

By default, ElectricSQL collects aggregated, anonymous usage data and sends them to our telemetry service. See Reference -> Telemetry for more information.

It's extremely helpful to leave telemetry enabled if you can.

Variable	Description
ELECTRIC_TELEMETRY   (enabled)	Telemetry mode. Telemetry is enabled by default. Set to disabled to disable collection.

Networking requirements

It's important to note that Postgres and Electric must be able to connect to each other. Specifically:

1. the Electric sync service connects to Postgres using the DATABASE_URL environment variable
2. Postgres connects to Electric to consume a logical replication publication using the LOGICAL_PUBLISHER_HOST (and LOGICAL_PUBLISHER_PORT) environment variables

         |<--------DATABASE_URL----------|
Postgres |                               | Electric
         |-----LOGICAL_PUBLISHER_HOST--->|

As a result, you must make sure (in terms of networking / firewalls) not only that Postgres is reachable from Electric but also that Electric is reachable from Postgres. And Electric must know its own address, in order to provide it to Postgres when setting up the logical replication publication that allows writes to be replicated into Postgres.