# `Electric`
[🔗](https://github.com/electric-sql/electric/tree/%40core/sync-service%401.5.1/packages/sync-service/lib/electric.ex#L1)

## Configuration options

When embedding Electric, the following options are available:

    config :electric,
      connection_opts: nil
      # Database
      provided_database_id: "single_stack",
      db_pool_size: 20,
      replication_stream_id: "default",
      replication_slot_temporary?: false,
      max_txn_size: 262144000,
      # HTTP API
      service_port: 3000,
      allow_shape_deletion?: false,
      cache_max_age: 60,
      cache_stale_age: 300,
      chunk_bytes_threshold: 10485760,
      listen_on_ipv6?: false,
      # Storage
      storage_dir: "./persistent",
      storage: {Electric.ShapeCache.PureFileStorage, [storage_dir: "./persistent/shapes"]},
      persistent_kv: {Electric.PersistentKV.Filesystem, :new!, [root: "./persistent/state"]},
      # Telemetry
      instance_id: nil,
      telemetry_statsd_host: nil,
      prometheus_port: nil,
      call_home_telemetry?: false,
      telemetry_url: %URI{scheme: "https", userinfo: nil, host: "checkpoint.electric-sql.com", port: 443, path: nil, query: nil, fragment: nil},

Only the `connection_opts` are required.

### Database

- `replication_connection_opts` - **Required**
     * `:hostname` (`t:String.t/0`) - Required. Server hostname

  * `:port` (`t:integer/0`) - Required. Server port

  * `:database` (`t:String.t/0`) - Required. Database

  * `:username` (`t:String.t/0`) - Required. Username

  * `:password` - Required. User password

  * `:sslmode` - Connection SSL configuration. See https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS The default value is `:prefer`.

  * `:ipv6` (`t:boolean/0`) - Whether to use IPv6 for database connections The default value is `false`.

  * `:cacertfile` (`t:String.t/0`) - The path to a file containing trusted certificate(s) that will be used to verify the certificate obtained from the database server during the TLS handshake

.
- `query_connection_opts` - Optional separate connection string that can use a pooler for non-replication queries (default: nil)
     * `:hostname` (`t:String.t/0`) - Required. Server hostname

  * `:port` (`t:integer/0`) - Required. Server port

  * `:database` (`t:String.t/0`) - Required. Database

  * `:username` (`t:String.t/0`) - Required. Username

  * `:password` - Required. User password

  * `:sslmode` - Connection SSL configuration. See https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS The default value is `:prefer`.

  * `:ipv6` (`t:boolean/0`) - Whether to use IPv6 for database connections The default value is `false`.

  * `:cacertfile` (`t:String.t/0`) - The path to a file containing trusted certificate(s) that will be used to verify the certificate obtained from the database server during the TLS handshake

.
- `db_pool_size` - How many connections Electric opens as a pool for handling shape queries (default: `20`)
- `replication_stream_id` - Suffix for the logical replication publication and slot name (default: `"default"`)

### HTTP API

- `service_port` (`t:integer/0`) - Port that the [HTTP API](https://electric-sql.com/docs/api/http) is exposed on (default: `3000`)
- `allow_shape_deletion?` (`t:boolean/0`) - Whether to allow deletion of Shapes via the HTTP API (default: `false`)
- `cache_max_age` (`t:integer/0`) - Default `max-age` for the cache headers of the HTTP API in seconds (default: `60`s)
- `cache_stale_age` (`t:integer/0`) - Default `stale-age` for the cache headers of the HTTP API in seconds (default: `300`s)
- `chunk_bytes_threshold` (`t:integer/0`) - Limit the maximum size in bytes of a shape log response,
  to ensure they are cached by upstream caches. (default: `10485760` (10MiB)).
- `listen_on_ipv6?` (`t:boolean/0`) - Whether the HTTP API should listen on IPv6 as well as IPv4 (default: `false`)

### Storage

- `storage_dir` (`t:String.t/0`) - Path to root folder for storing data on the filesystem (default: `"./persistent"`)
- `storage` (`t:Electric.ShapeCache.Storage.storage/0`) - Where to store shape logs. Must be a 2-tuple of `{module(),
  term()}` where `module` points to an implementation of the
  `Electric.ShapeCache.Storage` behaviour. (default: `{Electric.ShapeCache.PureFileStorage, [storage_dir: "./persistent/shapes"]}`)
- `persistent_kv` (`t:Electric.PersistentKV.t/0`) - A mfa that when called constructs an implementation of
  the `Electric.PersistentKV` behaviour, used to store system state (default: `{Electric.PersistentKV.Filesystem, :new!, [root: "./persistent/state"]}`)

### Telemetry

- `instance_id` (`t:binary/0`) - A unique identifier for the Electric instance. Set this to
  enable tracking of instance usage metrics across restarts, otherwise will be
  randomly generated at boot (default: a randomly generated UUID).
- `telemetry_statsd_host` (`t:String.t/0`) - If set, send telemetry data to the given StatsD reporting endpoint (default: `nil`)
- `prometheus_port` (`t:integer/0`) - If set, expose a prometheus reporter for telemetry data on the specified port (default: `nil`)
- `call_home_telemetry?` (`t:boolean/0`) - Allow [anonymous usage
  data](https://electric-sql.com/docs/reference/telemetry#anonymous-usage-data)
  about the instance being sent to a central checkpoint service (default: `true` for production)
- `telemetry_url` (`t:URI.t/0`) - Where to send the usage data (default: `%URI{scheme: "https", userinfo: nil, host: "checkpoint.electric-sql.com", port: 443, path: nil, query: nil, fragment: nil}`)

### Deprecated

- `provided_database_id` (`t:binary/0`) - The provided database id is relevant if you had
  used v0.8 and want to keep the storage instead of having hanging files. We
  use a provided value as stack id, but nothing else.

# `oid_relation`

```elixir
@type oid_relation() :: {oid :: relation_id(), relation :: relation()}
```

# `pg_connection_opts`

```elixir
@type pg_connection_opts() :: [
  hostname: binary(),
  port: integer(),
  database: binary(),
  username: binary(),
  password: binary() | (-> term()),
  sslmode: :disable | :allow | :prefer | :require,
  ipv6: boolean(),
  cacertfile: binary()
]
```

# `relation`

```elixir
@type relation() :: {schema :: String.t(), table :: String.t()}
```

# `relation_id`

```elixir
@type relation_id() :: non_neg_integer()
```

# `shape_handle`

```elixir
@type shape_handle() :: binary()
```

# `stack_id`

```elixir
@type stack_id() :: binary()
```

# `stack_events_registry`

# `telemetry_enabled?`

# `version`

---

*Consult [api-reference.md](api-reference.md) for complete listing*