diff --git a/docs/06-concepts/06-scheduling/05-configuration.md b/docs/06-concepts/06-scheduling/05-configuration.md index 2d346446..508922a6 100644 --- a/docs/06-concepts/06-scheduling/05-configuration.md +++ b/docs/06-concepts/06-scheduling/05-configuration.md @@ -1,5 +1,5 @@ --- -description: Future call settings cover execution, concurrency, the scan interval, and broken-call handling, set in config files or environment variables. +description: Future call settings cover enabling future calls, execution, concurrency, the scan interval, and broken-call handling, set in config files or environment variables. --- # Configuration @@ -8,28 +8,41 @@ You configure future calls in your Serverpod config files or through environment | Option | Default | Controls | | --- | --- | --- | -| `futureCallExecutionEnabled` | `true` | Whether this server runs future calls at all. | +| `futureCall.enabled` | `true` | Whether future calls can be scheduled and executed. | +| `futureCall.executionEnabled` | `true` | Whether this server runs due calls. Scheduling still works. | | `futureCall.concurrencyLimit` | `1` | How many calls may run at once. | | `futureCall.scanInterval` | `5000` | How often, in milliseconds, the server checks for due calls. | | `futureCall.checkBrokenCalls` | unset | Whether to scan for broken calls on startup. | | `futureCall.deleteBrokenCalls` | `false` | Whether to delete broken calls that are found. | ```yaml -futureCallExecutionEnabled: true - futureCall: + enabled: true # default + executionEnabled: true # default concurrencyLimit: 1 # default scanInterval: 5000 # default, in milliseconds ``` +## Disable future calls + +The `futureCall.enabled` option turns future calls off completely. It is `true` by default. When set to `false`, calls can neither be scheduled nor executed. Use it when your project does not use future calls. + +```yaml +futureCall: + enabled: false +``` + +If you schedule a call while it is off, the server throws a `StateError` with the message `FutureCalls is not initialized.` Future calls also need a database. Without one, they are off regardless of this option. + ## Execution options ### Enable or disable execution -The `futureCallExecutionEnabled` option turns future call execution on or off for a server. It is `true` by default. Set it to `false` in environments where background tasks should not run, such as a staging server where you want to test API behavior without triggering scheduled work. +The `futureCall.executionEnabled` option turns future call execution on or off for a server. It is `true` by default. Unlike `futureCall.enabled`, it does not stop calls from being scheduled; they are stored and run by any server that has execution enabled. Set it to `false` in environments where background tasks should not run, such as a staging server where you want to test API behavior without triggering scheduled work. ```yaml -futureCallExecutionEnabled: false +futureCall: + executionEnabled: false ``` ### Concurrency limit diff --git a/docs/06-concepts/07-operations/06-scalability.md b/docs/06-concepts/07-operations/06-scalability.md index c91cc269..62bcd101 100644 --- a/docs/06-concepts/07-operations/06-scalability.md +++ b/docs/06-concepts/07-operations/06-scalability.md @@ -30,7 +30,7 @@ Use roles so request capacity and background work do not share the same scaling dart run bin/main.dart --mode production --role serverless ``` -Schedule a separate process in the `maintenance` role (for example once per minute) when request nodes run as `serverless`. On pure request nodes you can also set `futureCallExecutionEnabled` to `false`; see [Future call configuration](../scheduling/configuration). +Schedule a separate process in the `maintenance` role (for example once per minute) when request nodes run as `serverless`. On pure request nodes you can also disable execution with the `SERVERPOD_FUTURE_CALL_EXECUTION_ENABLED` environment variable set to `false`, so the maintenance process, which reads the same config file, keeps running calls; see [Future call configuration](../scheduling/configuration). ## Offload CPU work to isolates diff --git a/docs/06-concepts/lookups/configuration-reference.md b/docs/06-concepts/lookups/configuration-reference.md index ab08a01d..96491a9d 100644 --- a/docs/06-concepts/lookups/configuration-reference.md +++ b/docs/06-concepts/lookups/configuration-reference.md @@ -72,7 +72,8 @@ Ports, hosts, and connection settings for the API, Insights, and web servers, th | SERVERPOD_SESSION_LOG_RETENTION_COUNT | sessionLogs.retentionCount | - | Maximum number of session log entries to keep. Set to null to disable count-based cleanup. Defaults to `100000` only when `sessionLogs` is not configured at all. See [Purge old records](../operations/logging#purge-old-records). | | SERVERPOD_SESSION_CONSOLE_LOG_ENABLED | sessionLogs.consoleEnabled | - | Enables or disables logging session data to the console. Defaults to `true` if no database is configured or the run mode is `development`, otherwise `false`. | | SERVERPOD_SESSION_CONSOLE_LOG_FORMAT | sessionLogs.consoleLogFormat | - | The format for console logging of session data. Valid options are `text` and `json`. Defaults to `text` for run mode `development`, otherwise `json`. | -| SERVERPOD_FUTURE_CALL_EXECUTION_ENABLED | futureCallExecutionEnabled | true | Enables or disables the execution of future calls. | +| SERVERPOD_FUTURE_CALL_ENABLED | futureCall.enabled | true | Enables or disables future calls entirely. When disabled, future calls can neither be scheduled nor executed. | +| SERVERPOD_FUTURE_CALL_EXECUTION_ENABLED | futureCall.executionEnabled | true | Enables or disables the execution of future calls. | | SERVERPOD_FUTURE_CALL_CONCURRENCY_LIMIT | futureCall.concurrencyLimit | 1 | The maximum number of concurrent future calls allowed. If the value is negative or null, no limit is applied. | | SERVERPOD_FUTURE_CALL_SCAN_INTERVAL | futureCall.scanInterval | 5000 | The interval in milliseconds for scanning future calls | | SERVERPOD_FUTURE_CALL_CHECK_BROKEN_CALLS | futureCall.checkBrokenCalls | - | Enables or disables the automatic check for broken future calls on startup. By default, the server performs an automatic check if there are less than 1000 calls in the database. |