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 ( | 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 ( | Port number to use for reverse connections from Postgres. |
HTTP_PORT ( | 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 ( | 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:
|
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 |
AUTH_JWT_ISS | This optional setting allows you to specificy the "issuer" that will be matched against the 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 ( | Telemetry mode. Telemetry is enabled by default. Set to |
Networking requirements
It's important to note that Postgres and Electric must be able to connect to each other. Specifically:
- the Electric sync service connects to Postgres using the
DATABASE_URL
environment variable - Postgres connects to Electric to consume a logical replication publication using the
LOGICAL_PUBLISHER_HOST
(andLOGICAL_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.