From 75ad310501e97929158c584f3075496d7c398dfa Mon Sep 17 00:00:00 2001 From: Oleksii Sholik Date: Wed, 2 Sep 2026 21:18:59 +0200 Subject: [PATCH 1/2] Document ELECTRIC_SHAPE_SUSPEND_AFTER in the config reference Since #4284 consumers always hibernate after ELECTRIC_SHAPE_HIBERNATE_AFTER and, when suspension is enabled, terminate a further ELECTRIC_SHAPE_SUSPEND_AFTER later. The docs still described ELECTRIC_SHAPE_HIBERNATE_AFTER as the suspend timeout and had no entry for the new variable. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01GDTua3WEeQeDbcDjVTP395 --- website/docs/sync/api/config.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/website/docs/sync/api/config.md b/website/docs/sync/api/config.md index 0bd524305f..230960f2cb 100644 --- a/website/docs/sync/api/config.md +++ b/website/docs/sync/api/config.md @@ -379,11 +379,13 @@ Port that the [HTTP API](/docs/sync/api/http) is exposed on. defaultValue="false" example="true"> -Whether to terminate idle shape consumer processes after `ELECTRIC_SHAPE_HIBERNATE_AFTER` seconds. This saves on memory at the cost of slightly higher CPU usage. When receiving a transaction that contains changes matching a given shape, a consumer process is started to handle the update. If more transactions matching the shape appear within the time defined by `ELECTRIC_SHAPE_HIBERNATE_AFTER` then the consumer will remain active, if not it will be terminated. +Whether to terminate idle shape consumer processes. This saves on memory at the cost of slightly higher CPU usage. -If set to `false` the consumer processes will [hibernate](https://www.erlang.org/doc/apps/erts/erlang#hibernate/3) instead of terminating, meaning they still occupy some memory but are inactive until passed transaction operations to process. +A consumer process first [hibernates](https://www.erlang.org/doc/apps/erts/erlang#hibernate/3) after `ELECTRIC_SHAPE_HIBERNATE_AFTER` of inactivity. With this option enabled, a hibernated consumer that stays idle for a further `ELECTRIC_SHAPE_SUSPEND_AFTER` is terminated. When a transaction containing changes matching the shape arrives, the consumer process is started again to handle the update. -If you enable this feature then you should configure `ELECTRIC_SHAPE_HIBERNATE_AFTER` to match the usage patterns of your application to avoid unnecessary process churn. +If set to `false` the consumer processes only hibernate, meaning they still occupy some memory but are inactive until passed transaction operations to process. + +If you enable this feature then you should configure `ELECTRIC_SHAPE_SUSPEND_AFTER` to match the usage patterns of your application to avoid unnecessary process churn. @@ -394,7 +396,18 @@ If you enable this feature then you should configure `ELECTRIC_SHAPE_HIBERNATE_A defaultValue="30s" example="5000ms"> -The amount of time a consumer process remains active without receiving transaction operations before either [hibernating](https://www.erlang.org/doc/apps/erts/erlang#hibernate/3) or terminating (if `ELECTRIC_SHAPE_SUSPEND_CONSUMER` is `true`). +The amount of time a consumer process remains active without receiving transaction operations before [hibernating](https://www.erlang.org/doc/apps/erts/erlang#hibernate/3). + + + +### ELECTRIC_SHAPE_SUSPEND_AFTER + + + +The amount of time a hibernated consumer process remains idle before being terminated. Only applies when `ELECTRIC_SHAPE_SUSPEND_CONSUMER` is `true`. Counted from the moment the consumer hibernates, so an idle consumer is terminated roughly `ELECTRIC_SHAPE_HIBERNATE_AFTER` plus `ELECTRIC_SHAPE_SUSPEND_AFTER` after its last activity. From b0d9b1c79c2708089ccffa8d4e819c83a6822db0 Mon Sep 17 00:00:00 2001 From: Oleksii Sholik Date: Wed, 2 Sep 2026 21:24:04 +0200 Subject: [PATCH 2/2] Note which shape consumers are never suspended Shapes with subquery dependencies and shapes other shapes depend on only ever hibernate, even with ELECTRIC_SHAPE_SUSPEND_CONSUMER enabled. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01GDTua3WEeQeDbcDjVTP395 --- website/docs/sync/api/config.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/website/docs/sync/api/config.md b/website/docs/sync/api/config.md index 230960f2cb..b4cca526fe 100644 --- a/website/docs/sync/api/config.md +++ b/website/docs/sync/api/config.md @@ -383,6 +383,8 @@ Whether to terminate idle shape consumer processes. This saves on memory at the A consumer process first [hibernates](https://www.erlang.org/doc/apps/erts/erlang#hibernate/3) after `ELECTRIC_SHAPE_HIBERNATE_AFTER` of inactivity. With this option enabled, a hibernated consumer that stays idle for a further `ELECTRIC_SHAPE_SUSPEND_AFTER` is terminated. When a transaction containing changes matching the shape arrives, the consumer process is started again to handle the update. +Not every consumer process is eligible for termination. Shapes with [subquery](/docs/sync/guides/shapes#subqueries) dependencies and shapes that other shapes depend on through a subquery, can only hibernate; they never get suspended. + If set to `false` the consumer processes only hibernate, meaning they still occupy some memory but are inactive until passed transaction operations to process. If you enable this feature then you should configure `ELECTRIC_SHAPE_SUSPEND_AFTER` to match the usage patterns of your application to avoid unnecessary process churn.