From c475a86edb8e046dbc31b77ae1c9787ec65c2318 Mon Sep 17 00:00:00 2001 From: Marcelo Soares Date: Tue, 18 Aug 2026 11:30:38 -0300 Subject: [PATCH 1/3] docs: State that the legacy streaming API is removed in 4.0 --- docs/06-concepts/02-endpoints-and-apis/02-sessions.md | 1 - docs/06-concepts/02-endpoints-and-apis/04-streaming.md | 4 ++-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/06-concepts/02-endpoints-and-apis/02-sessions.md b/docs/06-concepts/02-endpoints-and-apis/02-sessions.md index 5823abde..75c519eb 100644 --- a/docs/06-concepts/02-endpoints-and-apis/02-sessions.md +++ b/docs/06-concepts/02-endpoints-and-apis/02-sessions.md @@ -21,7 +21,6 @@ Serverpod creates a session for every unit of work it runs, and the type reflect | **MethodCallSession** | `Future` [endpoint methods](../endpoints-and-apis) | Single request | API calls, CRUD operations | | **WebCallSession** | [Web server](../web-server/overview) routes | Single request | Web pages, form submissions | | **MethodStreamSession** | [Streaming methods](./streaming) | Stream duration | Real-time updates, chat | -| **StreamingSession** | WebSocket connections of the [deprecated streaming endpoints API](./streaming#streaming-endpoints-deprecated) | Connection duration | Legacy real-time code | | **FutureCallSession** | [Scheduled tasks](../scheduling/overview) | Task execution | Email sending, batch jobs | | **InternalSession** | [Manual creation](#create-a-session-for-background-work) | Until closed | Background work, migrations | diff --git a/docs/06-concepts/02-endpoints-and-apis/04-streaming.md b/docs/06-concepts/02-endpoints-and-apis/04-streaming.md index f11a59f5..a13dafb1 100644 --- a/docs/06-concepts/02-endpoints-and-apis/04-streaming.md +++ b/docs/06-concepts/02-endpoints-and-apis/04-streaming.md @@ -191,6 +191,6 @@ await client.chat.postToRoom(roomId, 'Hello, room!'); Because the channel name includes the `roomId`, each client receives updates only for the room it is watching. The same pattern works for any filter: scope the channel by the id or query you care about, and post to it whenever the data changes. To fan the updates out across multiple server instances, enable Redis (see [Message scope](./server-events#message-scope)). -## Streaming endpoints (deprecated) +## Streaming endpoints (removed) -Serverpod's original streaming API (`streamOpened`, `handleStreamMessage`, `sendStreamMessage`, `openStreamingConnection`) is deprecated and will be removed in a future version. Use [streaming methods](#streaming-methods) instead. The old API is kept for reference in [Streaming endpoints (deprecated)](../../upgrading/archive/streaming-endpoints). +Serverpod's original streaming API (`streamOpened`, `handleStreamMessage`, `sendStreamMessage`, `openStreamingConnection`) was removed in 4.0. Use [streaming methods](#streaming-methods) instead. The old API is documented in [Streaming endpoints (deprecated)](../../upgrading/archive/streaming-endpoints) for projects still on 3.x. From 03bcfdbd1e27f83587f307ed188fea53a8e0646c Mon Sep 17 00:00:00 2001 From: Marcelo Soares Date: Thu, 20 Aug 2026 22:57:12 -0300 Subject: [PATCH 2/3] fix: Make the documentation more comprehensive --- docs/06-concepts/02-endpoints-and-apis/04-streaming.md | 4 ---- docs/11-upgrading/01-upgrade-to-four.md | 6 ++++++ docs/11-upgrading/02-archive/07-streaming-endpoints.md | 6 +++--- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/06-concepts/02-endpoints-and-apis/04-streaming.md b/docs/06-concepts/02-endpoints-and-apis/04-streaming.md index a13dafb1..5e5f5fac 100644 --- a/docs/06-concepts/02-endpoints-and-apis/04-streaming.md +++ b/docs/06-concepts/02-endpoints-and-apis/04-streaming.md @@ -190,7 +190,3 @@ await client.chat.postToRoom(roomId, 'Hello, room!'); ``` Because the channel name includes the `roomId`, each client receives updates only for the room it is watching. The same pattern works for any filter: scope the channel by the id or query you care about, and post to it whenever the data changes. To fan the updates out across multiple server instances, enable Redis (see [Message scope](./server-events#message-scope)). - -## Streaming endpoints (removed) - -Serverpod's original streaming API (`streamOpened`, `handleStreamMessage`, `sendStreamMessage`, `openStreamingConnection`) was removed in 4.0. Use [streaming methods](#streaming-methods) instead. The old API is documented in [Streaming endpoints (deprecated)](../../upgrading/archive/streaming-endpoints) for projects still on 3.x. diff --git a/docs/11-upgrading/01-upgrade-to-four.md b/docs/11-upgrading/01-upgrade-to-four.md index bb1d1bb0..831f18d4 100644 --- a/docs/11-upgrading/01-upgrade-to-four.md +++ b/docs/11-upgrading/01-upgrade-to-four.md @@ -84,6 +84,12 @@ Then refresh the generated server and client code: $ serverpod generate ``` +## If you use the legacy streaming endpoints API + +Serverpod's legacy streaming endpoints API was deprecated in 3.0 and is removed in 4.0. Endpoints that use the `StreamingSession` type no longer compile, and all the related server and client methods (e.g. `streamOpened`, `streamClosed`, `handleStreamMessage`, `sendStreamMessage`, `getUserObject`, `setUserObject`, `openStreamingConnection`) are gone. + +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. + ## 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: diff --git a/docs/11-upgrading/02-archive/07-streaming-endpoints.md b/docs/11-upgrading/02-archive/07-streaming-endpoints.md index a48d7ac9..5ad89af9 100644 --- a/docs/11-upgrading/02-archive/07-streaming-endpoints.md +++ b/docs/11-upgrading/02-archive/07-streaming-endpoints.md @@ -1,11 +1,11 @@ --- -description: The deprecated streaming endpoints API (streamOpened, handleStreamMessage, sendStreamMessage, openStreamingConnection). Use streaming methods instead. +description: The streaming endpoints API removed in Serverpod 4.0 (streamOpened, handleStreamMessage, openStreamingConnection). Use streaming methods instead. --- -# Streaming endpoints (deprecated) +# Streaming endpoints (removed in 4.0) :::warning -Streaming endpoints are deprecated and will be removed in a future version of Serverpod. Use [streaming methods](../../concepts/endpoints-and-apis/streaming#streaming-methods) instead for a simpler and more reliable streaming experience. This page is kept for projects still on the old API. +Streaming endpoints were deprecated in Serverpod 3.0 and removed in 4.0. Use [streaming methods](../../concepts/endpoints-and-apis/streaming#streaming-methods) instead. This page documents the old API for projects that have not ported off it yet. ::: Streaming endpoints were Serverpod's first attempt at streaming data. This approach is more manual, requiring you to manage the WebSocket connection to the server. From 07f91536d7d71e54ed953c6a6b0699232bd90b2b Mon Sep 17 00:00:00 2001 From: Marcelo Soares Date: Fri, 21 Aug 2026 09:04:04 -0300 Subject: [PATCH 3/3] docs: Address review on the streaming API removal --- docs/06-concepts/07-operations/02-logging.md | 12 +++++------- docs/11-upgrading/01-upgrade-to-four.md | 2 +- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/06-concepts/07-operations/02-logging.md b/docs/06-concepts/07-operations/02-logging.md index 15c577a1..780ff74a 100644 --- a/docs/06-concepts/07-operations/02-logging.md +++ b/docs/06-concepts/07-operations/02-logging.md @@ -6,12 +6,11 @@ description: Serverpod records a log entry for calls, queries, and your own mess Logging is how you find out what your server did after it did it: which calls ran, which queries were slow, and what failed. Serverpod records this for you, and you add your own messages on top. -There are four kinds of record, and the difference matters for everything below: +There are three kinds of record, and the difference matters for everything below: - **Session records** describe one unit of work, such as an endpoint call: how long it took, whether it failed, and which endpoint it hit. - **Query records** describe individual database queries run during that session. - **Log messages** are the entries you write yourself with `session.log`. -- **Stream messages** are the messages passed by [streaming](../endpoints-and-apis/streaming) sessions. ## Write your own messages @@ -38,16 +37,15 @@ Messages are collected while the session runs and written when it closes, whethe Records are written to the database, to the console, to both, or to neither. -In the database they land in four tables: +In the database they land in three tables: | Table | Holds | | --- | --- | | `serverpod_session_log` | One row per completed session. | | `serverpod_log` | Your `session.log` messages. | | `serverpod_query_log` | Database queries. | -| `serverpod_message_log` | Stream messages from streaming sessions. | -The last three reference the session row, so deleting a session row removes its queries and messages with it. +The last two reference the session row, so deleting a session row removes its queries with it. :::info The companion app [Serverpod Insights](../../tools/insights) reads and searches these tables, and can change the runtime settings described below. @@ -57,7 +55,7 @@ The companion app [Serverpod Insights](../../tools/insights) reads and searches Not every session produces a row, and the default depends on the run mode. -In `development`, every completed session is recorded. In `staging`, `production`, and `test`, a session is recorded only when it ran longer than one second, it failed, or it produced a log, query, or message entry. Ordinary fast calls leave no row, which keeps the table to the sessions worth looking at. +In `development`, every completed session is recorded. In `staging`, `production`, and `test`, a session is recorded only when it ran longer than one second, it failed, or it produced a log or query entry. Ordinary fast calls leave no row, which keeps the table to the sessions worth looking at. These thresholds are runtime settings stored in the `serverpod_runtime_settings` table, so you can change them on a running server through Insights without redeploying. They control whether all sessions are logged, whether all queries are logged, what counts as slow, and the minimum level a message must have to be kept. You can also override them per endpoint and per method. @@ -98,7 +96,7 @@ Every environment variable in the table takes a real value. Setting one to an em ## Purge old records -Log tables grow with every call your server handles, so Serverpod can delete old records for you. Cleanup runs on the `cleanupInterval`, and removes session rows that are either older than `retentionPeriod` or beyond the newest `retentionCount`, whichever applies first. Deleting a session row takes its query, message, and log rows with it. +Log tables grow with every call your server handles, so Serverpod can delete old records for you. Cleanup runs on the `cleanupInterval`, and removes session rows that are either older than `retentionPeriod` or beyond the newest `retentionCount`, whichever applies first. Deleting a session row takes its query and log rows with it. | Setting | Environment variable | Default | | --- | --- | --- | diff --git a/docs/11-upgrading/01-upgrade-to-four.md b/docs/11-upgrading/01-upgrade-to-four.md index 831f18d4..64cf6159 100644 --- a/docs/11-upgrading/01-upgrade-to-four.md +++ b/docs/11-upgrading/01-upgrade-to-four.md @@ -84,7 +84,7 @@ Then refresh the generated server and client code: $ serverpod generate ``` -## If you use the legacy streaming endpoints API +### If you use the legacy streaming endpoints API Serverpod's legacy streaming endpoints API was deprecated in 3.0 and is removed in 4.0. Endpoints that use the `StreamingSession` type no longer compile, and all the related server and client methods (e.g. `streamOpened`, `streamClosed`, `handleStreamMessage`, `sendStreamMessage`, `getUserObject`, `setUserObject`, `openStreamingConnection`) are gone.