diff --git a/docs/06-concepts/lookups/configuration-reference.md b/docs/06-concepts/lookups/configuration-reference.md index 4079fb90..ab556ffb 100644 --- a/docs/06-concepts/lookups/configuration-reference.md +++ b/docs/06-concepts/lookups/configuration-reference.md @@ -23,50 +23,51 @@ Set the run mode, server role, and boot behavior. Declare each per run mode in t Ports, hosts, and connection settings for the API, Insights, and web servers, the database, Redis, session logs, and future calls, plus a few options that exist only on the Dart config object. -| Environment variable | Config file | Default | Description | -| ----------------------------------------- | ----------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| SERVERPOD_API_SERVER_PORT | apiServer.port | 8080 | The port number for the API server | -| SERVERPOD_API_SERVER_PUBLIC_HOST | apiServer.publicHost | localhost | The public host address of the API server | -| SERVERPOD_API_SERVER_PUBLIC_PORT | apiServer.publicPort | 8080 | The public port number for the API server | -| SERVERPOD_API_SERVER_PUBLIC_SCHEME | apiServer.publicScheme | http | The public scheme (http/https) for the API server | -| SERVERPOD_INSIGHTS_SERVER_PORT | insightsServer.port | - | The port number for the Insights server | -| SERVERPOD_INSIGHTS_SERVER_PUBLIC_HOST | insightsServer.publicHost | - | The public host address of the Insights server | -| SERVERPOD_INSIGHTS_SERVER_PUBLIC_PORT | insightsServer.publicPort | - | The public port number for the Insights server | -| SERVERPOD_INSIGHTS_SERVER_PUBLIC_SCHEME | insightsServer.publicScheme | - | The public scheme (http/https) for the Insights server | -| SERVERPOD_WEB_SERVER_PORT | webServer.port | - | The port number for the Web server | -| SERVERPOD_WEB_SERVER_PUBLIC_HOST | webServer.publicHost | - | The public host address of the Web server | -| SERVERPOD_WEB_SERVER_PUBLIC_PORT | webServer.publicPort | - | The public port number for the Web server | -| SERVERPOD_WEB_SERVER_PUBLIC_SCHEME | webServer.publicScheme | - | The public scheme (http/https) for the Web server | -| SERVERPOD_DATABASE_HOST | database.host | - | The host address of the database | -| SERVERPOD_DATABASE_PORT | database.port | - | The port number for the database connection | -| SERVERPOD_DATABASE_NAME | database.name | - | The name of the database | -| SERVERPOD_DATABASE_USER | database.user | - | The user name for database authentication | -| SERVERPOD_DATABASE_SEARCH_PATHS | database.searchPaths | - | The search paths used for all database connections | -| SERVERPOD_DATABASE_REQUIRE_SSL | database.requireSsl | false | Indicates if SSL is required for the database | -| SERVERPOD_DATABASE_IS_UNIX_SOCKET | database.isUnixSocket | false | Specifies if the database connection is a Unix socket | -| SERVERPOD_DATABASE_MAX_CONNECTION_COUNT | database.maxConnectionCount | 10 | The maximum number of connections in the database pool. Set to 0 or a negative value for unlimited connections. | -| SERVERPOD_DATABASE_FILE_PATH | database.filePath | - | The SQLite database file path. Set this instead of host/port/name/user when using SQLite. | -| SERVERPOD_DATABASE_DIALECT | database.dialect | postgres | The database dialect. Valid options are `postgres` and `sqlite`. | -| SERVERPOD_DATABASE_DATA_PATH | database.dataPath | - | Directory for the embedded PostgreSQL cluster, relative to the server package unless absolute. When set, Serverpod starts or attaches to the cluster before connecting. PostgreSQL only; ignored for SQLite. | -| SERVERPOD_REDIS_HOST | redis.host | - | The host address of the Redis server | -| SERVERPOD_REDIS_PORT | redis.port | - | The port number for the Redis server | -| SERVERPOD_REDIS_USER | redis.user | - | The user name for Redis authentication | -| SERVERPOD_REDIS_ENABLED | redis.enabled | false | Indicates if Redis is enabled | -| SERVERPOD_REDIS_REQUIRE_SSL | redis.requireSsl | false | Indicates if SSL is required for the Redis connection | -| SERVERPOD_MAX_REQUEST_SIZE | maxRequestSize | 524288 | The maximum size of requests allowed in bytes | -| SERVERPOD_VALIDATE_HEADERS | validateHeaders | true | Validate HTTP headers using the typed API. Set to `false` to accept headers without the required formatting, for example an unwrapped token in the Authorization header. | -| SERVERPOD_SESSION_PERSISTENT_LOG_ENABLED | sessionLogs.persistentEnabled | - | Enables or disables logging session data to the database. Defaults to `true` if a database is configured, otherwise `false`. | -| SERVERPOD_SESSION_LOG_CLEANUP_INTERVAL | sessionLogs.cleanupInterval | 24h | How often to run the log cleanup job. Duration string (e.g. `24h`, `2d`). Set to null to disable automated purging. | -| SERVERPOD_SESSION_LOG_RETENTION_PERIOD | sessionLogs.retentionPeriod | 90d | How long to keep session log entries. Duration string (e.g. `30d`, `60d`). Set to null to disable time-based cleanup. | -| SERVERPOD_SESSION_LOG_RETENTION_COUNT | sessionLogs.retentionCount | 100000 | Maximum number of session log entries to keep. Set to null to disable count-based cleanup. | -| 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_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. | -| SERVERPOD_FUTURE_CALL_DELETE_BROKEN_CALLS | futureCall.deleteBrokenCalls | false | Enables or disables the deletion of broken future calls when running the check on startup. | -| SERVERPOD_WEBSOCKET_PING_INTERVAL | websocketPingInterval | 30 | The interval in seconds between WebSocket ping messages sent to keep streaming connections alive. Must be a positive integer. | +| Environment variable | Config file | Default | Description | +| ------------------------------------------------ | ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| SERVERPOD_API_SERVER_PORT | apiServer.port | 8080 | The port number for the API server | +| SERVERPOD_API_SERVER_PUBLIC_HOST | apiServer.publicHost | localhost | The public host address of the API server | +| SERVERPOD_API_SERVER_PUBLIC_PORT | apiServer.publicPort | 8080 | The public port number for the API server | +| SERVERPOD_API_SERVER_PUBLIC_SCHEME | apiServer.publicScheme | http | The public scheme (http/https) for the API server | +| SERVERPOD_INSIGHTS_SERVER_PORT | insightsServer.port | - | The port number for the Insights server | +| SERVERPOD_INSIGHTS_SERVER_PUBLIC_HOST | insightsServer.publicHost | - | The public host address of the Insights server | +| SERVERPOD_INSIGHTS_SERVER_PUBLIC_PORT | insightsServer.publicPort | - | The public port number for the Insights server | +| SERVERPOD_INSIGHTS_SERVER_PUBLIC_SCHEME | insightsServer.publicScheme | - | The public scheme (http/https) for the Insights server | +| SERVERPOD_INSIGHTS_SERVER_ENABLE_DATABASE_ACCESS | insightsServer.enableDatabaseAccess | false | Whether the Insights server serves the direct database access endpoints (used by custom service client tooling, not the Insights app) | +| SERVERPOD_WEB_SERVER_PORT | webServer.port | - | The port number for the Web server | +| SERVERPOD_WEB_SERVER_PUBLIC_HOST | webServer.publicHost | - | The public host address of the Web server | +| SERVERPOD_WEB_SERVER_PUBLIC_PORT | webServer.publicPort | - | The public port number for the Web server | +| SERVERPOD_WEB_SERVER_PUBLIC_SCHEME | webServer.publicScheme | - | The public scheme (http/https) for the Web server | +| SERVERPOD_DATABASE_HOST | database.host | - | The host address of the database | +| SERVERPOD_DATABASE_PORT | database.port | - | The port number for the database connection | +| SERVERPOD_DATABASE_NAME | database.name | - | The name of the database | +| SERVERPOD_DATABASE_USER | database.user | - | The user name for database authentication | +| SERVERPOD_DATABASE_SEARCH_PATHS | database.searchPaths | - | The search paths used for all database connections | +| SERVERPOD_DATABASE_REQUIRE_SSL | database.requireSsl | false | Indicates if SSL is required for the database | +| SERVERPOD_DATABASE_IS_UNIX_SOCKET | database.isUnixSocket | false | Specifies if the database connection is a Unix socket | +| SERVERPOD_DATABASE_MAX_CONNECTION_COUNT | database.maxConnectionCount | 10 | The maximum number of connections in the database pool. Set to 0 or a negative value for unlimited connections. | +| SERVERPOD_DATABASE_FILE_PATH | database.filePath | - | The SQLite database file path. Set this instead of host/port/name/user when using SQLite. | +| SERVERPOD_DATABASE_DIALECT | database.dialect | postgres | The database dialect. Valid options are `postgres` and `sqlite`. | +| SERVERPOD_DATABASE_DATA_PATH | database.dataPath | - | Directory for the embedded PostgreSQL cluster, relative to the server package unless absolute. When set, Serverpod starts or attaches to the cluster before connecting. PostgreSQL only; ignored for SQLite. | +| SERVERPOD_REDIS_HOST | redis.host | - | The host address of the Redis server | +| SERVERPOD_REDIS_PORT | redis.port | - | The port number for the Redis server | +| SERVERPOD_REDIS_USER | redis.user | - | The user name for Redis authentication | +| SERVERPOD_REDIS_ENABLED | redis.enabled | false | Indicates if Redis is enabled | +| SERVERPOD_REDIS_REQUIRE_SSL | redis.requireSsl | false | Indicates if SSL is required for the Redis connection | +| SERVERPOD_MAX_REQUEST_SIZE | maxRequestSize | 524288 | The maximum size of requests allowed in bytes | +| SERVERPOD_VALIDATE_HEADERS | validateHeaders | true | Validate HTTP headers using the typed API. Set to `false` to accept headers without the required formatting, for example an unwrapped token in the Authorization header. | +| SERVERPOD_SESSION_PERSISTENT_LOG_ENABLED | sessionLogs.persistentEnabled | - | Enables or disables logging session data to the database. Defaults to `true` if a database is configured, otherwise `false`. | +| SERVERPOD_SESSION_LOG_CLEANUP_INTERVAL | sessionLogs.cleanupInterval | 24h | How often to run the log cleanup job. Duration string (e.g. `24h`, `2d`). Set to null to disable automated purging. | +| SERVERPOD_SESSION_LOG_RETENTION_PERIOD | sessionLogs.retentionPeriod | 90d | How long to keep session log entries. Duration string (e.g. `30d`, `60d`). Set to null to disable time-based cleanup. | +| SERVERPOD_SESSION_LOG_RETENTION_COUNT | sessionLogs.retentionCount | 100000 | Maximum number of session log entries to keep. Set to null to disable count-based cleanup. | +| 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_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. | +| SERVERPOD_FUTURE_CALL_DELETE_BROKEN_CALLS | futureCall.deleteBrokenCalls | false | Enables or disables the deletion of broken future calls when running the check on startup. | +| SERVERPOD_WEBSOCKET_PING_INTERVAL | websocketPingInterval | 30 | The interval in seconds between WebSocket ping messages sent to keep streaming connections alive. Must be a positive integer. | ### Dart-only options diff --git a/docs/10-tools/01-insights.md b/docs/10-tools/01-insights.md index 7946fb17..15ff6a0d 100644 --- a/docs/10-tools/01-insights.md +++ b/docs/10-tools/01-insights.md @@ -13,3 +13,18 @@ Serverpod has a companion app. It is currently available for Mac and Windows, bu | Serverpod 1.2.0 | [Download](https://downloads.serverpod.dev/macos/Serverpod-1.2.0.zip) | [Download](https://downloads.serverpod.dev/windows/serverpod-1.2.0.zip) | | Serverpod 1.1.0 | [Download](https://downloads.serverpod.dev/macos/Serverpod-1.1.0.zip) | [Download](https://downloads.serverpod.dev/windows/serverpod-1.1.0.zip) | | Serverpod 1.0.0 | [Download](https://serverpod.dev/insights/Serverpod-1.0.0.zip) | n/a | + +## Database access + +The Insights server also exposes endpoints that read and write your database directly (`fetchDatabaseBulkData`, `runQueries`, `getDatabaseRowCount`, and `executeSql`). The Insights app doesn't use them; they exist only to support custom tooling built on the `serverpod_service_client` package. They are disabled by default and throw an `AccessDeniedException` unless you explicitly enable them in the server configuration: + +```yaml +insightsServer: + port: 8081 + publicHost: localhost + publicPort: 8081 + publicScheme: http + enableDatabaseAccess: true +``` + +The same setting is available as the `SERVERPOD_INSIGHTS_SERVER_ENABLE_DATABASE_ACCESS` environment variable. Since the flag gives anyone holding the service secret full read and write access to the database, leave it off unless you have custom service client tooling that needs it. diff --git a/docs/11-upgrading/01-upgrade-to-four.md b/docs/11-upgrading/01-upgrade-to-four.md index 73d03d56..4fa8ec7f 100644 --- a/docs/11-upgrading/01-upgrade-to-four.md +++ b/docs/11-upgrading/01-upgrade-to-four.md @@ -90,6 +90,21 @@ Serverpod's legacy streaming endpoints API was deprecated in 3.0 and is removed Port that code to [streaming methods](../concepts/endpoints-and-apis/streaming), where the endpoint declares `Stream` parameters and return types, and Serverpod manages the connection. State that used to live in a user object becomes a local variable in the streaming method, which stays alive as long as the stream is open. The old API stays documented in [Streaming endpoints](./archive/streaming-endpoints) while you port. +### If you use the Insights database endpoints from a service client + +The Insights server endpoints that give direct database access (`fetchDatabaseBulkData`, `runQueries`, `getDatabaseRowCount`, and `executeSql`) are disabled by default in 4.0 and throw an `AccessDeniedException` until enabled. The Insights app doesn't use these endpoints, so most projects need no change. If you have custom tooling that calls them through the `serverpod_service_client` package, opt in per environment with `enableDatabaseAccess` in the `insightsServer` block of the config file (or the `SERVERPOD_INSIGHTS_SERVER_ENABLE_DATABASE_ACCESS` environment variable): + +```yaml +insightsServer: + port: 8081 + publicHost: localhost + publicPort: 8081 + publicScheme: http + enableDatabaseAccess: true +``` + +The `hotReload`, `getOpenSessionLog`, and `shutdown` Insights methods are removed. See [Insights](../tools/insights#database-access) for details. + ## Generate the 4.0 migration Version 4.0 adds a few new internal Serverpod tables and updates some indexes to greatly improve logs performance on Insights. Create a migration that captures these schema deltas so your database can be brought up to date: