From 2d091306e0b1b1b7c025c749403e664f3e7e2a14 Mon Sep 17 00:00:00 2001 From: Preston Date: Tue, 25 Aug 2026 08:39:08 -0500 Subject: [PATCH 1/2] Added docs for insights endpoints that are disabled by default. --- .../lookups/configuration-reference.md | 89 ++++++++++--------- docs/10-tools/01-insights.md | 15 ++++ docs/11-upgrading/01-upgrade-to-four.md | 15 ++++ 3 files changed, 75 insertions(+), 44 deletions(-) diff --git a/docs/06-concepts/lookups/configuration-reference.md b/docs/06-concepts/lookups/configuration-reference.md index 4079fb90..fd7834f3 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 database access endpoints (browse tables, run queries) | +| 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..3cad10e9 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 + +Insights can browse tables and run SQL queries against your database, but that access is disabled by default. The endpoints that serve it (`fetchDatabaseBulkData`, `runQueries`, `getDatabaseRowCount`, and `executeSql`) return 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, keep it off in production unless you need it. diff --git a/docs/11-upgrading/01-upgrade-to-four.md b/docs/11-upgrading/01-upgrade-to-four.md index 73d03d56..63b838d1 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 Insights database access + +The Insights endpoints that give database access (`fetchDatabaseBulkData`, `runQueries`, `getDatabaseRowCount`, and `executeSql`) are disabled by default in 4.0 and throw an `AccessDeniedException` until enabled. If you rely on them, for example to browse tables from the Insights app, 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: From 5845f1c750f17902e8c4621b357dd12fc4eac54a Mon Sep 17 00:00:00 2001 From: Preston Date: Thu, 27 Aug 2026 14:09:53 -0500 Subject: [PATCH 2/2] Clarify that the Insights app does not use the database endpoints. --- docs/06-concepts/lookups/configuration-reference.md | 2 +- docs/10-tools/01-insights.md | 4 ++-- docs/11-upgrading/01-upgrade-to-four.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/06-concepts/lookups/configuration-reference.md b/docs/06-concepts/lookups/configuration-reference.md index fd7834f3..ab556ffb 100644 --- a/docs/06-concepts/lookups/configuration-reference.md +++ b/docs/06-concepts/lookups/configuration-reference.md @@ -33,7 +33,7 @@ Ports, hosts, and connection settings for the API, Insights, and web servers, th | 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 database access endpoints (browse tables, run queries) | +| 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 | diff --git a/docs/10-tools/01-insights.md b/docs/10-tools/01-insights.md index 3cad10e9..15ff6a0d 100644 --- a/docs/10-tools/01-insights.md +++ b/docs/10-tools/01-insights.md @@ -16,7 +16,7 @@ Serverpod has a companion app. It is currently available for Mac and Windows, bu ## Database access -Insights can browse tables and run SQL queries against your database, but that access is disabled by default. The endpoints that serve it (`fetchDatabaseBulkData`, `runQueries`, `getDatabaseRowCount`, and `executeSql`) return an `AccessDeniedException` unless you explicitly enable them in the server configuration: +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: @@ -27,4 +27,4 @@ insightsServer: 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, keep it off in production unless you need it. +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 63b838d1..4fa8ec7f 100644 --- a/docs/11-upgrading/01-upgrade-to-four.md +++ b/docs/11-upgrading/01-upgrade-to-four.md @@ -90,9 +90,9 @@ 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 Insights database access +### If you use the Insights database endpoints from a service client -The Insights endpoints that give database access (`fetchDatabaseBulkData`, `runQueries`, `getDatabaseRowCount`, and `executeSql`) are disabled by default in 4.0 and throw an `AccessDeniedException` until enabled. If you rely on them, for example to browse tables from the Insights app, opt in per environment with `enableDatabaseAccess` in the `insightsServer` block of the config file (or the `SERVERPOD_INSIGHTS_SERVER_ENABLE_DATABASE_ACCESS` environment variable): +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: