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 options are DATABASE_URL and ELECTRIC_SECRET.

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

Variable DATABASE_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.

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

ELECTRIC_QUERY_DATABASE_URL

Variable	`ELECTRIC_QUERY_DATABASE_URL`
Default	`DATABASE_URL`
Description	Postgres connection string. Used to connect to the Postgres database for anything but the replication, will default to the same as `DATABASE_URL` if not provided. 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. This can point to a connection pooler and does not need a `REPLICATION` role as it does not handle the replication. For a secure connection, set the `sslmode` query parameter to `require`.
Example	`ELECTRIC_QUERY_DATABASE_URL=postgresql://user:password@example-pooled.com:54321/electric`

ELECTRIC_DATABASE_USE_IPV6

Variable	`ELECTRIC_DATABASE_USE_IPV6`
Default	`false`
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.
Example	`ELECTRIC_DATABASE_USE_IPV6=true`

ELECTRIC_DB_POOL_SIZE

Variable	`ELECTRIC_DB_POOL_SIZE`
Default	`20`
Description	How many connections Electric opens as a pool for handling shape queries.
Example	`ELECTRIC_DB_POOL_SIZE=10`

ELECTRIC_DATABASE_CA_CERTIFICATE_FILE

Variable ELECTRIC_DATABASE_CA_CERTIFICATE_FILEoptional

Description

The path on local disk to a file containing trusted certificate(s) that Electric will use to verify the database server identity.

Trusted certificates are those that have been signed by trusted certificate authorities (CA); they are also known as root certificates. Every operating system and most web browsers include a bundle of well-known root certificates (aka CA store). You can instruct Electric to use the default bundle provided by your OS by specifying an absolute path to it. This page from Neon lists the typical locations for different operating systems.

Some managed Postgres providers such as Supabase and DigitalOcean use a self-signed root certificate that won't be found in OS-specific CA stores. If you're using one of those, download the trusted certificate from the provider's website and put it somewhere on your local disk where Electric can access it.

Certificate verification and sslmode

Electric doesn't support sslmode=verify-ca or sslmode=verify-full query params in DATABASE_URL. Those values are specific to psql. When you configure Electric with a trusted certificate file, it will always try to verify the server identity and will refuse to open a database connection if the verification does not succeed.

Note, however, that setting sslmode=disable in DATABASE_URL and enabling certificate verification at the same time will result in a startup error.

Example ELECTRIC_DATABASE_CA_CERTIFICATE_FILE=/root/.postgresql/root.crt

ELECTRIC_REPLICATION_STREAM_ID

Variable	`ELECTRIC_REPLICATION_STREAM_ID`
Default	`default`
Description	Suffix for the logical replication publication and slot name.
Example	`ELECTRIC_REPLICATION_STREAM_ID=my-app`

ELECTRIC_MANUAL_TABLE_PUBLISHING

Variable	`ELECTRIC_MANUAL_TABLE_PUBLISHING`
Default	`false`
Description	Set to `true` to disable automatic addition/removal of database tables from the publication in Postgres. In order to receive realtime updates as soon as they are committed in Postgres, Electric maintains a publication inside the database and automatically adds tables to it for which shape subscriptions are established. This only works if Electric's database role owns the table or is granted the group role that owns the table. If your permissions policies prevent Electric from using a role that can alter application tables, set this setting to `true` and manually add each table to the publication by executing sql `BEGIN; ALTER PUBLICATION electric_publication_default ADD TABLE <my table>; ALTER TABLE <my table> REPLICA IDENTITY FULL; COMMIT;` before requesting a new shape for that table.
Example	`ELECTRIC_MANUAL_TABLE_PUBLISHING=true`

Electric

ELECTRIC_SECRET

Variable	`ELECTRIC_SECRET`required
Description	Secret for shape requests to the HTTP API. This is required unless `ELECTRIC_INSECURE` is set to `true`. By default, the Electric API is public and authorises all shape requests against this secret. More details are available in the security guide.
Example	`ELECTRIC_SECRET=1U6ItbhoQb4kGUU5wXBLbxvNf`

ELECTRIC_INSECURE

Variable	`ELECTRIC_INSECURE`
Default	`false`
Description	When set to `true`, runs Electric in insecure mode and does not require an `ELECTRIC_SECRET`. Use with caution. API requests are unprotected and may risk exposing your database. Good for development environments. If used in production, make sure to lock down access to Electric.
Example	`ELECTRIC_INSECURE=true`

ELECTRIC_INSTANCE_ID

Variable	`ELECTRIC_INSTANCE_ID`
Default	`Electric.Utils.uuid4()`
Description	A unique identifier for the Electric instance. Defaults to a randomly generated UUID.
Example	`ELECTRIC_INSTANCE_ID=some-unique-instance-identifier`

ELECTRIC_SERVICE_NAME

Variable	`ELECTRIC_SERVICE_NAME`
Default	`electric`
Description	Name of the electric service. Used as a resource name in OTEL traces and metrics.
Example	`ELECTRIC_SERVICE_NAME=my-electric-service`

ELECTRIC_LISTEN_ON_IPV6

Variable	`ELECTRIC_LISTEN_ON_IPV6`
Default	`false`
Description	By default, Electric binds to IPv4. Enable this to listen on IPv6 addresses as well.
Example	`ELECTRIC_LISTEN_ON_IPV6=true`

ELECTRIC_TCP_SEND_TIMEOUT

Variable	`ELECTRIC_TCP_SEND_TIMEOUT`
Default	`30s`
Description	Timeout for sending a response chunk back to the client. Defaults to 30 seconds. Slow response processing on the client or bandwidth restristrictions can cause TCP backpressure leading to the error message: `Error while streaming response: :timeout` This environment variable increases this timeout.
Example	`ELECTRIC_TCP_SEND_TIMEOUT=60s`

ELECTRIC_SHAPE_CHUNK_BYTES_THRESHOLD

Variable	`ELECTRIC_SHAPE_CHUNK_BYTES_THRESHOLD`
Default	`10485760`
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.
Example	`ELECTRIC_SHAPE_CHUNK_BYTES_THRESHOLD=20971520`

ELECTRIC_PORT

Variable	`ELECTRIC_PORT`
Default	`3000`
Description	Port that the HTTP API is exposed on.
Example	`ELECTRIC_PORT=8080`

Caching

ELECTRIC_CACHE_MAX_AGE

Variable	`ELECTRIC_CACHE_MAX_AGE`
Default	`60`
Description	Default `max-age` for the cache headers of the HTTP API.
Example	`ELECTRIC_CACHE_MAX_AGE=5`

ELECTRIC_CACHE_STALE_AGE

Variable	`ELECTRIC_CACHE_STALE_AGE`
Default	`300`
Description	Default `stale-age` for the cache headers of the HTTP API.
Example	`ELECTRIC_CACHE_STALE_AGE=5`

Storage

ELECTRIC_PERSISTENT_STATE

Variable	`ELECTRIC_PERSISTENT_STATE`
Default	`FILE`
Description	Where to store shape metadata. Defaults to storing on the filesystem. If provided must be one of `MEMORY` or `FILE`.
Example	`ELECTRIC_PERSISTENT_STATE=MEMORY`

ELECTRIC_STORAGE

Variable	`ELECTRIC_STORAGE`
Default	`FAST_FILE`
Description	Where to store shape logs. Defaults to storing on the filesystem. If provided must be one of `MEMORY` or `FAST_FILE`.
Example	`ELECTRIC_STORAGE=MEMORY`

ELECTRIC_STORAGE_DIR

Variable	`ELECTRIC_STORAGE_DIR`
Default	`./persistent`
Description	Path to root folder for storing data on the filesystem.
Example	`ELECTRIC_STORAGE_DIR=/var/example`

Telemetry

These environment variables allow configuration of metric and trace export for visibility into performance of the Electric instance.

ELECTRIC_OTLP_ENDPOINT

Variable	`ELECTRIC_OTLP_ENDPOINT`optional
Description	Set an OpenTelemetry endpoint URL to enable telemetry.
Example	`ELECTRIC_OTLP_ENDPOINT=https://example.com`

ELECTRIC_OTEL_DEBUG

Variable	`ELECTRIC_OTEL_DEBUG`
Default	`false`
Description	Debug tracing by printing spans to stdout, without batching.
Example	`ELECTRIC_OTEL_DEBUG=true`

ELECTRIC_HNY_API_KEY

Variable	`ELECTRIC_HNY_API_KEY`optional
Description	Honeycomb.io api key. Specify along with `HNY_DATASET` to export traces directly to Honeycomb, without the need to run an OpenTelemetry Collector.
Example	`ELECTRIC_HNY_API_KEY=your-api-key`

ELECTRIC_HNY_DATASET

Variable	`ELECTRIC_HNY_DATASET`optional
Description	Name of your Honeycomb Dataset.
Example	`ELECTRIC_HNY_DATASET=your-dataset-name`

ELECTRIC_PROMETHEUS_PORT

Variable	`ELECTRIC_PROMETHEUS_PORT`optional
Description	Expose a prometheus reporter for telemetry data on the specified port.
Example	`ELECTRIC_PROMETHEUS_PORT=9090`

ELECTRIC_STATSD_HOST

Variable	`ELECTRIC_STATSD_HOST`optional
Description	Enable sending telemetry data to a StatsD reporting endpoint.
Example	`ELECTRIC_STATSD_HOST=https://example.com`

Logging

ELECTRIC_LOG_LEVEL

Variable ELECTRIC_LOG_LEVELoptional

Description

Verbosity of Electric's log output.

Available levels, in the order of increasing verbosity:

error
warning
info
debug

Example ELECTRIC_LOG_LEVEL=debug

ELECTRIC_LOG_COLORS

Variable ELECTRIC_LOG_COLORSoptional

Description

Enable or disable ANSI coloring of Electric's log output.

By default, coloring is enabled when Electric's stdout is connected to a terminal. This may be undesirable in certain runtime environments, such as AWS which displays ANSI color codes using escape sequences and may incorrectly split log entries into multiple lines.

Example ELECTRIC_LOG_COLORS=false

ELECTRIC_LOG_OTP_REPORTS

Variable	`ELECTRIC_LOG_OTP_REPORTS`
Default	`false`
Description	Enable OTP SASL reporting at runtime.
Example	`ELECTRIC_LOG_OTP_REPORTS=true`

Usage reporting

ELECTRIC_USAGE_REPORTING

These environment variables allow configuration of anonymous usage data reporting back to https://electric-sql.com

Variable	`ELECTRIC_USAGE_REPORTING`
Default	`true`
Description	Configure anonymous usage data about the instance being sent to a central checkpoint service. Collected information is anonymised and doesn't contain any information from the replicated data. You can read more about it in our telemetry docs.
Example	`ELECTRIC_USAGE_REPORTING=true`

Sync service configuration ​

Configuration ​

Database ​

DATABASE_URL ​

ELECTRIC_QUERY_DATABASE_URL ​

ELECTRIC_DATABASE_USE_IPV6 ​

ELECTRIC_DB_POOL_SIZE ​

ELECTRIC_DATABASE_CA_CERTIFICATE_FILE ​

ELECTRIC_REPLICATION_STREAM_ID ​

ELECTRIC_MANUAL_TABLE_PUBLISHING ​

Electric ​

ELECTRIC_SECRET ​

ELECTRIC_INSECURE ​

ELECTRIC_INSTANCE_ID ​

ELECTRIC_SERVICE_NAME ​

ELECTRIC_LISTEN_ON_IPV6 ​

ELECTRIC_TCP_SEND_TIMEOUT ​

ELECTRIC_SHAPE_CHUNK_BYTES_THRESHOLD ​

ELECTRIC_PORT ​

Caching ​

ELECTRIC_CACHE_MAX_AGE ​

ELECTRIC_CACHE_STALE_AGE ​

Storage ​

ELECTRIC_PERSISTENT_STATE ​

ELECTRIC_STORAGE ​

ELECTRIC_STORAGE_DIR ​

Telemetry ​

ELECTRIC_OTLP_ENDPOINT ​

ELECTRIC_OTEL_DEBUG ​

ELECTRIC_HNY_API_KEY ​

ELECTRIC_HNY_DATASET ​

ELECTRIC_PROMETHEUS_PORT ​

ELECTRIC_STATSD_HOST ​

Logging ​

ELECTRIC_LOG_LEVEL ​

ELECTRIC_LOG_COLORS ​

ELECTRIC_LOG_OTP_REPORTS ​

Usage reporting ​

ELECTRIC_USAGE_REPORTING ​

Sync service configuration

Configuration

Database

DATABASE_URL

ELECTRIC_QUERY_DATABASE_URL

ELECTRIC_DATABASE_USE_IPV6

ELECTRIC_DB_POOL_SIZE

ELECTRIC_DATABASE_CA_CERTIFICATE_FILE

ELECTRIC_REPLICATION_STREAM_ID

ELECTRIC_MANUAL_TABLE_PUBLISHING

Electric

ELECTRIC_SECRET

ELECTRIC_INSECURE

ELECTRIC_INSTANCE_ID

ELECTRIC_SERVICE_NAME

ELECTRIC_LISTEN_ON_IPV6

ELECTRIC_TCP_SEND_TIMEOUT

ELECTRIC_SHAPE_CHUNK_BYTES_THRESHOLD

ELECTRIC_PORT

Caching

ELECTRIC_CACHE_MAX_AGE

ELECTRIC_CACHE_STALE_AGE

Storage

ELECTRIC_PERSISTENT_STATE

ELECTRIC_STORAGE

ELECTRIC_STORAGE_DIR

Telemetry

ELECTRIC_OTLP_ENDPOINT

ELECTRIC_OTEL_DEBUG

ELECTRIC_HNY_API_KEY

ELECTRIC_HNY_DATASET

ELECTRIC_PROMETHEUS_PORT

ELECTRIC_STATSD_HOST

Logging

ELECTRIC_LOG_LEVEL

ELECTRIC_LOG_COLORS

ELECTRIC_LOG_OTP_REPORTS

Usage reporting

ELECTRIC_USAGE_REPORTING