Skip to content

Sync service configuration

This page documents the config options for self-hosting the Electric sync engine.

Advanced only

You don't need to worry about this if you're using Electric Cloud.

Also, the only required configuration is DATABASE_URL.

Configuration

The sync engine is an Elixir application developed at packages/sync-service and published as a Docker image at electricsql/electric.

Configuration options can be provided as environment variables, e.g.:

shell
docker run \
    -e "DATABASE_URL=postgresql://..." \
    -e "ELECTRIC_DB_POOL_SIZE=10" \
    -p 3000:3000 \
    electricsql/electric

These are passed into the application via config/runtime.exs.

Database

DATABASE_URL

VariableDATABASE_URLrequired
Description

Postgres connection string. Used to connect to the Postgres database.

The connection string must be in the libpg Connection URI format of postgresql://[userspec@][hostspec][/dbname][?sslmode=<sslmode>].

The userspec section of the connection string specifies the database user that Electric connects to Postgres as. They must have the REPLICATION role.

For a secure connection, set the sslmode query parameter to require.

ExampleDATABASE_URL=postgresql://user:password@example.com:54321/electric

ELECTRIC_DATABASE_USE_IPV6

VariableELECTRIC_DATABASE_USE_IPV6
Defaultfalse
Description

Set to true to prioritise connecting to the database over IPv6. Electric will fall back to an IPv4 DNS lookup if the IPv6 lookup fails.

ExampleELECTRIC_DATABASE_USE_IPV6=true

ELECTRIC_DB_POOL_SIZE

VariableELECTRIC_DB_POOL_SIZE
Default20
Description

How many connections Electric opens as a pool for handling shape queries.

ExampleELECTRIC_DB_POOL_SIZE=10

ELECTRIC_REPLICATION_STREAM_ID

VariableELECTRIC_REPLICATION_STREAM_ID
Defaultdefault
Description

Suffix for the logical replication publication and slot name.

ExampleELECTRIC_REPLICATION_STREAM_ID=my-app

Electric

ELECTRIC_INSTANCE_ID

VariableELECTRIC_INSTANCE_ID
DefaultElectric.Utils.uuid4()
Description

A unique identifier for the Electric instance. Defaults to a randomly generated UUID.

ExampleELECTRIC_INSTANCE_ID=some-unique-instance-identifier

ELECTRIC_SERVICE_NAME

VariableELECTRIC_SERVICE_NAME
Defaultelectric
Description

Name of the electric service. Used as a resource identifier and namespace.

ExampleELECTRIC_SERVICE_NAME=my-electric-service

ELECTRIC_ENABLE_INTEGRATION_TESTING

VariableELECTRIC_ENABLE_INTEGRATION_TESTING
Defaultfalse
Description

Expose some unsafe operations that faciliate integration testing. Do not enable this production.

ExampleELECTRIC_ENABLE_INTEGRATION_TESTING=true

ELECTRIC_LISTEN_ON_IPV6

VariableELECTRIC_LISTEN_ON_IPV6
Defaultfalse
Description

By default, Electric binds to IPv4. Enable this to listen on IPv6 addresses as well.

ExampleELECTRIC_LISTEN_ON_IPV6=true

ELECTRIC_LOG_CHUNK_BYTES_THRESHOLD

VariableELECTRIC_LOG_CHUNK_BYTES_THRESHOLD
Default10485760
Description

Limit the maximum size of a shape log response, to ensure they are cached by upstream caches. Defaults to 10MB (10 * 1024 * 1024). See #1581 for context.

ExampleELECTRIC_LOG_CHUNK_BYTES_THRESHOLD=20971520

ELECTRIC_LOG_OTP_REPORTS

VariableELECTRIC_LOG_OTP_REPORTS
Defaultfalse
Description

Enable OTP SASL reporting at runtime.

ExampleELECTRIC_LOG_OTP_REPORTS=true

ELECTRIC_PORT

VariableELECTRIC_PORT
Default3000
Description

Port that the HTTP API is exposed on.

ExampleELECTRIC_PORT=8080

Caching

ELECTRIC_CACHE_MAX_AGE

VariableELECTRIC_CACHE_MAX_AGE
Default60
Description

Default max-age for the cache headers of the HTTP API.

ExampleELECTRIC_CACHE_MAX_AGE=5

ElECTRIC_CACHE_STALE_AGE

VariableELECTRIC_CACHE_STALE_AGE
Default300
Description

Default stale-age for the cache headers of the HTTP API.

ExampleELECTRIC_CACHE_STALE_AGE=5

Storage

ELECTRIC_PERSISTENT_STATE

VariableELECTRIC_PERSISTENT_STATE
DefaultFILE
Description

Where to store shape metadata. Defaults to storing on the filesystem. If provided must be one of MEMORY or FILE.

ExampleELECTRIC_PERSISTENT_STATE=MEMORY

ELECTRIC_STORAGE

VariableELECTRIC_STORAGE
DefaultFILE
Description

Where to store shape logs. Defaults to storing on the filesystem. If provided must be one of MEMORY or FILE.

ExampleELECTRIC_STORAGE=MEMORY

ELECTRIC_STORAGE_DIR

VariableELECTRIC_STORAGE_DIR
Default./persistent
Description

Path to root folder for storing data on the filesystem.

ExampleELECTRIC_STORAGE_DIR=/var/example

Telemetry

ELECTRIC_OTLP_ENDPOINT

VariableELECTRIC_OTLP_ENDPOINToptional
Description

Set an OpenTelemetry endpoint URL to enable telemetry.

ExampleELECTRIC_OTLP_ENDPOINT=https://example.com

ELECTRIC_OTEL_DEBUG

VariableELECTRIC_OTEL_DEBUG
Defaultfalse
Description

Debug tracing by printing spans to stdout, without batching.

ExampleELECTRIC_OTEL_DEBUG=true

ELECTRIC_HNY_API_KEY

VariableELECTRIC_HNY_API_KEYoptional
Description

Honeycomb.io api key. Specify along with HNY_DATASET to export traces directly to Honeycomb, without the need to run an OpenTelemetry Collector.

ExampleELECTRIC_HNY_API_KEY=your-api-key

ELECTRIC_HNY_DATASET

VariableELECTRIC_HNY_DATASEToptional
Description

Name of your Honeycomb Dataset.

ExampleELECTRIC_HNY_DATASET=your-dataset-name

ELECTRIC_PROMETHEUS_PORT

VariableELECTRIC_PROMETHEUS_PORToptional
Description

Expose a prometheus reporter for telemetry data on the specified port.

ExampleELECTRIC_PROMETHEUS_PORT=9090

ELECTRIC_STATSD_HOST

VariableELECTRIC_STATSD_HOSToptional
Description

Enable sending telemetry data to a StatsD reporting endpoint.

ExampleELECTRIC_STATSD_HOST=https://example.com