From 406f33145e75b40af9a4b4d9d55d8a585f616344 Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Mon, 1 Jun 2026 13:00:48 +0100 Subject: [PATCH 1/8] docs: Add migration guide for upgrading to Serverpod 3.5 --- docs/11-upgrading/05-upgrade-to-three-five.md | 178 ++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 docs/11-upgrading/05-upgrade-to-three-five.md diff --git a/docs/11-upgrading/05-upgrade-to-three-five.md b/docs/11-upgrading/05-upgrade-to-three-five.md new file mode 100644 index 00000000..b0866cf2 --- /dev/null +++ b/docs/11-upgrading/05-upgrade-to-three-five.md @@ -0,0 +1,178 @@ +--- +title: Upgrade to 3.5 +description: Upgrade your Serverpod 3.4 project to 3.5 (Jetstream) by adopting serverpod start, the embedded Postgres option, and the new agent skills. +--- + + + +# Upgrade to 3.5 + +Serverpod 3.5 (Jetstream) ships a new development workflow (`serverpod start`), an embedded Postgres option, and built-in agent skills. The changes are mostly opt-in: your existing 3.4 project keeps working with small updates. + +This guide walks through the upgrade and should take about 15 minutes. + +## Before you start + +- Your project is on the latest Serverpod 3.4.x release. +- Your project compiles and tests pass. +- You've committed your current state to git so you can roll back if needed. + +## Update the Serverpod CLI + +Install the 3.5 CLI: + +```bash +$ dart pub global activate serverpod_cli 3.5.0-beta.9 +``` + +Verify the version: + +```bash +$ serverpod version +``` + +## Update your project dependencies + +In each package's `pubspec.yaml` (`_server`, `_client`, `_flutter`), bump the Serverpod packages to 3.5. Serverpod prefers an exact version pin over a caret range to keep the CLI and the packages in sync: + +```yaml +dependencies: + serverpod: 3.5.0-beta.9 + serverpod_client: 3.5.0-beta.9 # in the client and Flutter packages + serverpod_flutter: 3.5.0-beta.9 # in the Flutter package +``` + +Also bump the Dart SDK constraint in the root `pubspec.yaml` and `_server/pubspec.yaml` to match the 3.5 minimum: + +```yaml +environment: + sdk: '^3.10.3' +``` + +From the project's root folder, refresh dependencies (Dart workspaces resolve all sub-packages in one command), then regenerate the server and client code: + +```bash +$ dart pub upgrade +$ serverpod generate +``` + +## Generate the 3.5 migration + +3.5 adds a few new internal Serverpod tables and updates some indexes (such as `serverpod_future_call_claim` and indexes on `serverpod_log` and `serverpod_query_log`). Create a migration that captures these schema deltas so your database can be brought up to date: + +```bash +$ serverpod create-migration +``` + +This writes a new migration to `_server/migrations/`. It will be applied to your database in the next step. + +## Adopt the new development workflow + +3.5 replaces the `docker compose up` + `dart bin/main.dart` + `flutter run` triad with a single command, `serverpod start`, which runs the server, the database, and your Flutter app together with hot reload. Before running it, choose how to handle the database. + +### Choose your data store + +You can either switch to the new embedded Postgres or keep your existing Docker Postgres. The choice depends on whether you have development data you need to keep. + +**Path A: switch to the embedded Postgres.** Add `dataPath` to the database section of `_server/config/development.yaml` and `_server/config/testing.yaml`: + +```yaml +database: + host: localhost + port: 8090 + name: + user: postgres + dataPath: .serverpod/dev/pgdata +``` + +For `testing.yaml`, use a separate directory, for example `dataPath: .serverpod/test/pgdata`. + +:::warning + +The embedded Postgres uses a fresh data directory, separate from your Docker volumes. If you have seeded development data you need to keep, follow Path B, or import your data into the new directory after switching. + +::: + +**Path B: keep your Docker Postgres.** No config change. You'll pass `--docker` to `serverpod start` so it uses your existing `docker-compose.yaml`. + +:::warning + +Make sure Docker is running before `serverpod start --docker`. If it isn't, `serverpod start` may fall back to the embedded Postgres path and connect your app to an empty database. This is harmless, but it can look like your data disappeared. Your Docker data is still in its volume. Start Docker and re-run `serverpod start --docker` to reconnect. + +::: + +### Start the server + +From the project's root folder, run: + +```bash +$ serverpod start # Path A (embedded Postgres) +# or: +$ serverpod start --docker # Path B (Docker Postgres) +``` + +The first run compiles the native build hooks (this can take ~30 seconds) and applies the migration you generated above. The server then starts, watches your project, and hot-reloads on save. + +## Add the agent skills (optional) + +3.5 ships AI agent skills (for editors like Claude Code and Cursor) and an MCP server. Install them with: + +```bash +$ dart install skills +``` + +From your project's root folder, install the skills for your editor: + +```bash +$ skills get --ide cursor +``` + +Replace `cursor` with the editor you use: `antigravity`, `claude`, `cline`, `codex`, `copilot`, `cursor`, `opencode`, or `generic`. + +## Production deployment notes + +Your production Dockerfile pattern (`dart compile exe bin/main.dart -o bin/server`) continues to work in 3.5. Build hooks run automatically during compilation. The only change you may need is to bump the Dart SDK base image to 3.10.x or newer: + +```dockerfile +FROM dart:3.10.3 AS build +``` + +The embedded Postgres is a development convenience and does not run in production. Use a managed Postgres for your deployed server: [Serverpod Cloud](/cloud) provisions one for you automatically, or you can connect to a managed service like Cloud SQL or RDS. + +## What's new in 3.5 + +- **`serverpod start` TUI**: hot reload on save, **R** to hot restart, **M** to create a migration, **A** to apply migrations, **P** to apply a repair migration. +- **Flutter app spawning** from `serverpod start` so the Flutter app runs alongside the server in the same TUI. +- **AI agent skills and MCP server** scaffolded during `serverpod create`; existing projects opt in with `dart install skills` and `skills get`. +- **Embedded Postgres**: zero-Docker development via `dataPath`. +- **SQLite database support** as an alternative dialect to Postgres. +- **Client-side database generation** for the Flutter app. +- **`jsonb` column support** with GIN index operator classes, and **`dynamic` fields** on models and endpoints. +- **`unique` keyword** for simpler unique indexes in model files. +- **`upsert` and `upsertRow`** on the ORM, and **`asc()` / `desc()`** convenience methods on orderable columns. +- **Recurring future calls** via the new claim-based scheduling. +- **OAuth2 PKCE Flutter web redirect** for sign-in flows. +- **Health endpoints** on the built-in webserver. +- **IDE and agent selection** in `serverpod create`. + +### Migration concerns + +These are not new features but can affect existing 3.4 projects: + +- **`serverpod_database` package extraction.** Database types and helpers moved from `serverpod` into a new `serverpod_database` package. If you imported database APIs directly from `serverpod`, some of those imports now come from `serverpod_database`. The compiler will point out any imports that need updating after you run `dart pub upgrade`. +- **Logging revamp.** The logging API was reworked. If you have custom log handling, review your code against the new API. + +## Troubleshooting + +### Port conflicts on `serverpod start` + +A previous `serverpod start` or a separate Postgres process may still be listening on 8090 or 8080. Stop the other process, or run on different ports. + +### Agent skills aren't picked up after install + +Run `skills get` again from the project's root folder. Some editors, like Cursor, require enabling the MCP server in their settings. + +## Related + +- [Migrations](../06-concepts/06-database/11-migrations.md): how Serverpod's migration system works under the hood. +- [Build your first app](../05-build-your-first-app/01-creating-endpoints.md): the hands-on tour of the 3.5 workflow if you want to see `serverpod start` from scratch. From 21c6800ea42fc52851deff98f763f447cc4f8db9 Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Mon, 1 Jun 2026 13:24:11 +0100 Subject: [PATCH 2/8] docs: Archive pre-3.5 upgrade pages and reorder chronologically --- docs/06-concepts/02-models/03-vector-fields.md | 2 +- ...{05-upgrade-to-three-five.md => 01-upgrade-to-three-five.md} | 0 .../01-upgrade-to-one-point-two.md} | 0 .../03-upgrade-to-two.md => 02-archive/02-upgrade-to-two.md} | 0 .../03-upgrade-from-mini.md} | 0 .../{04-archive => 02-archive}/04-upgrade-to-two-point-two.md | 0 .../05-upgrade-to-pgvector.md} | 2 +- .../06-upgrade-to-three.md} | 0 docs/11-upgrading/{04-archive => 02-archive}/_category_.json | 0 9 files changed, 2 insertions(+), 2 deletions(-) rename docs/11-upgrading/{05-upgrade-to-three-five.md => 01-upgrade-to-three-five.md} (100%) rename docs/11-upgrading/{04-archive/02-upgrade-to-one-point-two.md => 02-archive/01-upgrade-to-one-point-two.md} (100%) rename docs/11-upgrading/{04-archive/03-upgrade-to-two.md => 02-archive/02-upgrade-to-two.md} (100%) rename docs/11-upgrading/{02-upgrade-from-mini.md => 02-archive/03-upgrade-from-mini.md} (100%) rename docs/11-upgrading/{04-archive => 02-archive}/04-upgrade-to-two-point-two.md (100%) rename docs/11-upgrading/{03-upgrade-to-pgvector.md => 02-archive/05-upgrade-to-pgvector.md} (97%) rename docs/11-upgrading/{01-upgrade-to-three.md => 02-archive/06-upgrade-to-three.md} (100%) rename docs/11-upgrading/{04-archive => 02-archive}/_category_.json (100%) diff --git a/docs/06-concepts/02-models/03-vector-fields.md b/docs/06-concepts/02-models/03-vector-fields.md index 75e4d7c8..6a76ad45 100644 --- a/docs/06-concepts/02-models/03-vector-fields.md +++ b/docs/06-concepts/02-models/03-vector-fields.md @@ -13,7 +13,7 @@ All vector types support specialized distance operations for similarity search a To ensure optimal performance with vector similarity searches, consider creating specialized vector indexes on your vector fields. See the [Vector indexes](../database/indexing#vector-indexes) section for more details. :::info -The usage of Vector fields requires the pgvector PostgreSQL extension to be installed, which comes by default on new Serverpod projects. To upgrade an existing project, see the [Upgrade to pgvector](../../upgrading/upgrade-to-pgvector) guide. +The usage of Vector fields requires the pgvector PostgreSQL extension to be installed, which comes by default on new Serverpod projects. To upgrade an existing project, see the [Upgrade to pgvector](../../11-upgrading/02-archive/05-upgrade-to-pgvector.md) guide. ::: ## Vector diff --git a/docs/11-upgrading/05-upgrade-to-three-five.md b/docs/11-upgrading/01-upgrade-to-three-five.md similarity index 100% rename from docs/11-upgrading/05-upgrade-to-three-five.md rename to docs/11-upgrading/01-upgrade-to-three-five.md diff --git a/docs/11-upgrading/04-archive/02-upgrade-to-one-point-two.md b/docs/11-upgrading/02-archive/01-upgrade-to-one-point-two.md similarity index 100% rename from docs/11-upgrading/04-archive/02-upgrade-to-one-point-two.md rename to docs/11-upgrading/02-archive/01-upgrade-to-one-point-two.md diff --git a/docs/11-upgrading/04-archive/03-upgrade-to-two.md b/docs/11-upgrading/02-archive/02-upgrade-to-two.md similarity index 100% rename from docs/11-upgrading/04-archive/03-upgrade-to-two.md rename to docs/11-upgrading/02-archive/02-upgrade-to-two.md diff --git a/docs/11-upgrading/02-upgrade-from-mini.md b/docs/11-upgrading/02-archive/03-upgrade-from-mini.md similarity index 100% rename from docs/11-upgrading/02-upgrade-from-mini.md rename to docs/11-upgrading/02-archive/03-upgrade-from-mini.md diff --git a/docs/11-upgrading/04-archive/04-upgrade-to-two-point-two.md b/docs/11-upgrading/02-archive/04-upgrade-to-two-point-two.md similarity index 100% rename from docs/11-upgrading/04-archive/04-upgrade-to-two-point-two.md rename to docs/11-upgrading/02-archive/04-upgrade-to-two-point-two.md diff --git a/docs/11-upgrading/03-upgrade-to-pgvector.md b/docs/11-upgrading/02-archive/05-upgrade-to-pgvector.md similarity index 97% rename from docs/11-upgrading/03-upgrade-to-pgvector.md rename to docs/11-upgrading/02-archive/05-upgrade-to-pgvector.md index c46ec272..5c51361d 100644 --- a/docs/11-upgrading/03-upgrade-to-pgvector.md +++ b/docs/11-upgrading/02-archive/05-upgrade-to-pgvector.md @@ -68,7 +68,7 @@ $ serverpod create-migration $ dart run bin/main.dart --apply-migrations ``` -For more details on creating and applying migrations, see the [Migrations](../concepts/database/migrations) section. +For more details on creating and applying migrations, see the [Migrations](../../06-concepts/06-database/11-migrations.md) page. The pgvector extension will be automatically enabled during the first migration that includes a vector column. diff --git a/docs/11-upgrading/01-upgrade-to-three.md b/docs/11-upgrading/02-archive/06-upgrade-to-three.md similarity index 100% rename from docs/11-upgrading/01-upgrade-to-three.md rename to docs/11-upgrading/02-archive/06-upgrade-to-three.md diff --git a/docs/11-upgrading/04-archive/_category_.json b/docs/11-upgrading/02-archive/_category_.json similarity index 100% rename from docs/11-upgrading/04-archive/_category_.json rename to docs/11-upgrading/02-archive/_category_.json From 5a60804e7d7638fadc95be40d375ef6a79b16e42 Mon Sep 17 00:00:00 2001 From: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com> Date: Mon, 1 Jun 2026 16:34:31 +0100 Subject: [PATCH 3/8] chore: PR review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/11-upgrading/01-upgrade-to-three-five.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/11-upgrading/01-upgrade-to-three-five.md b/docs/11-upgrading/01-upgrade-to-three-five.md index b0866cf2..b1973588 100644 --- a/docs/11-upgrading/01-upgrade-to-three-five.md +++ b/docs/11-upgrading/01-upgrade-to-three-five.md @@ -15,7 +15,7 @@ This guide walks through the upgrade and should take about 15 minutes. - Your project is on the latest Serverpod 3.4.x release. - Your project compiles and tests pass. -- You've committed your current state to git so you can roll back if needed. +- You've committed your current state to Git so you can roll back if needed. ## Update the Serverpod CLI From 3b324c5f36834f1dffc8c07926c996f7b925afbc Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Tue, 2 Jun 2026 08:52:42 +0100 Subject: [PATCH 4/8] docs: Address review on Upgrade to 3.5 guide --- docs/11-upgrading/01-upgrade-to-three-five.md | 124 ++++++++++++------ 1 file changed, 86 insertions(+), 38 deletions(-) diff --git a/docs/11-upgrading/01-upgrade-to-three-five.md b/docs/11-upgrading/01-upgrade-to-three-five.md index b1973588..b3a99768 100644 --- a/docs/11-upgrading/01-upgrade-to-three-five.md +++ b/docs/11-upgrading/01-upgrade-to-three-five.md @@ -7,7 +7,7 @@ description: Upgrade your Serverpod 3.4 project to 3.5 (Jetstream) by adopting s # Upgrade to 3.5 -Serverpod 3.5 (Jetstream) ships a new development workflow (`serverpod start`), an embedded Postgres option, and built-in agent skills. The changes are mostly opt-in: your existing 3.4 project keeps working with small updates. +Serverpod 3.5 (Jetstream) brings a unified `serverpod start` command with hot reload that runs your server, database, and Flutter app together. The release also includes an embedded Postgres option and optional AI agent skills for your editor. The changes are mostly opt-in: your existing 3.4 project keeps working with small updates. This guide walks through the upgrade and should take about 15 minutes. @@ -22,7 +22,7 @@ This guide walks through the upgrade and should take about 15 minutes. Install the 3.5 CLI: ```bash -$ dart pub global activate serverpod_cli 3.5.0-beta.9 +$ dart install serverpod_cli 3.5.0-beta.9 ``` Verify the version: @@ -49,32 +49,66 @@ environment: sdk: '^3.10.3' ``` -From the project's root folder, refresh dependencies (Dart workspaces resolve all sub-packages in one command), then regenerate the server and client code: +From the project's root folder, refresh dependencies. Dart workspaces (used by projects created with the 3.3+ scaffold) resolve all sub-packages in one command: ```bash $ dart pub upgrade +``` + +If your project doesn't use a Dart workspace (there's no `workspace:` block in the root `pubspec.yaml`), run `dart pub upgrade` separately in each sub-package. To adopt workspaces, see Dart's [pub workspaces documentation](https://dart.dev/tools/pub/workspaces). + +Then refresh the generated server and client code: + +```bash $ serverpod generate ``` ## Generate the 3.5 migration -3.5 adds a few new internal Serverpod tables and updates some indexes (such as `serverpod_future_call_claim` and indexes on `serverpod_log` and `serverpod_query_log`). Create a migration that captures these schema deltas so your database can be brought up to date: +Version 3.5 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: ```bash -$ serverpod create-migration +$ serverpod create-migration --tag "upgrade-3.5" ``` This writes a new migration to `_server/migrations/`. It will be applied to your database in the next step. ## Adopt the new development workflow -3.5 replaces the `docker compose up` + `dart bin/main.dart` + `flutter run` triad with a single command, `serverpod start`, which runs the server, the database, and your Flutter app together with hot reload. Before running it, choose how to handle the database. +Version 3.5 introduces a faster, integrated development workflow. The new `serverpod start` command runs your server, your Flutter app, and (optionally) your database in a single watch process with hot reload, replacing the manual `docker compose up` + `dart bin/main.dart` + `flutter run` triad. The result is a tighter edit-save-see-result loop and built-in tooling for migrations, hot restart, and agent skills. + +Before running it, choose how to handle the database. ### Choose your data store -You can either switch to the new embedded Postgres or keep your existing Docker Postgres. The choice depends on whether you have development data you need to keep. +You have two paths. Pick the one that fits where you are today; both work with `serverpod start`. + +#### Keep your Docker Postgres (easiest upgrade) + +If you've been developing against a Docker Postgres on 3.4, you can keep it without changing your config. Pass `--docker` to `serverpod start` so it uses your existing `docker-compose.yaml`: + +```bash +$ serverpod start --docker +``` + +`serverpod start --docker` will start Docker for you if it isn't running, and will tear down the compose stack on exit if it was the one that started it. + +#### Switch to the embedded Postgres (recommended for new development) + +Version 3.5 ships a built-in Postgres that runs as a child process of your Dart server, using the same Postgres dialect as production. It has practical advantages over Docker for day-to-day development: + +**Pros:** -**Path A: switch to the embedded Postgres.** Add `dataPath` to the database section of `_server/config/development.yaml` and `_server/config/testing.yaml`: +- No Docker dependency. +- No TCP port conflicts (uses a Unix domain socket by default). +- Cleanup by deleting the data directory. + +**Trade-offs:** + +- Tests must run with `--concurrency=1` (the cluster is single-tenant). +- Manual access (e.g. with `psql`) requires a Dart process to be running the cluster. + +To switch, add `dataPath` to the database section of `_server/config/development.yaml` and `_server/config/testing.yaml`: ```yaml database: @@ -87,35 +121,29 @@ database: For `testing.yaml`, use a separate directory, for example `dataPath: .serverpod/test/pgdata`. -:::warning - -The embedded Postgres uses a fresh data directory, separate from your Docker volumes. If you have seeded development data you need to keep, follow Path B, or import your data into the new directory after switching. +Once `dataPath` is set, `serverpod start` uses the embedded Postgres automatically: -::: +```bash +$ serverpod start +``` -**Path B: keep your Docker Postgres.** No config change. You'll pass `--docker` to `serverpod start` so it uses your existing `docker-compose.yaml`. +`dataPath` belongs in `development.yaml` and `testing.yaml` only. For production, use a managed Postgres: [Serverpod Cloud](/cloud) provisions one for you, or you can connect to a managed service like Cloud SQL or RDS. Do not add `dataPath` to `production.yaml` or `staging.yaml`. :::warning -Make sure Docker is running before `serverpod start --docker`. If it isn't, `serverpod start` may fall back to the embedded Postgres path and connect your app to an empty database. This is harmless, but it can look like your data disappeared. Your Docker data is still in its volume. Start Docker and re-run `serverpod start --docker` to reconnect. +If you've added `dataPath` to your config and also pass `--docker`, the server connects to the embedded Postgres rather than your Docker Postgres. `dataPath` is honored by the server process regardless of the `--docker` flag, which only controls whether `serverpod start` brings up the `docker-compose` stack. If that's not what you wanted, your Docker volume is still intact: remove `dataPath` from your config to use the Docker Postgres again. ::: ### Start the server -From the project's root folder, run: - -```bash -$ serverpod start # Path A (embedded Postgres) -# or: -$ serverpod start --docker # Path B (Docker Postgres) -``` +The first run compiles the native build hooks (this can take about 30 seconds) and applies the migration you generated above. The server then starts and watches your project; saving a file hot-reloads the code. -The first run compiles the native build hooks (this can take ~30 seconds) and applies the migration you generated above. The server then starts, watches your project, and hot-reloads on save. +`serverpod start` also launches your Flutter app, in Chrome by default. Pass `--flutter-device ` to target a different device. For IDE debugging, projects scaffolded with 3.5 include a `launch.json` that runs `serverpod start` with the debugger attached; you can copy that file into your existing project from a fresh 3.5 scaffold if you want the same setup. ## Add the agent skills (optional) -3.5 ships AI agent skills (for editors like Claude Code and Cursor) and an MCP server. Install them with: +Version 3.5 ships AI agent skills (for editors like Claude Code and Cursor) and an MCP server. Install them with: ```bash $ dart install skills @@ -127,17 +155,44 @@ From your project's root folder, install the skills for your editor: $ skills get --ide cursor ``` -Replace `cursor` with the editor you use: `antigravity`, `claude`, `cline`, `codex`, `copilot`, `cursor`, `opencode`, or `generic`. +Replace `cursor` with the editor you use: `antigravity`, `claude`, `cline`, `codex`, `copilot`, `cursor`, `opencode`, or `generic` to install at the `.agents` folder. ## Production deployment notes -Your production Dockerfile pattern (`dart compile exe bin/main.dart -o bin/server`) continues to work in 3.5. Build hooks run automatically during compilation. The only change you may need is to bump the Dart SDK base image to 3.10.x or newer: +Your production build needs to switch from `dart compile exe` to `dart build cli`. The 3.5 server includes native build hooks that `dart compile` doesn't support. The new build produces a bundle (executable plus its native libraries) rather than a single static binary, so your Dockerfile needs a few updates. -```dockerfile -FROM dart:3.10.3 AS build -``` +The fastest fix is to copy the updated Dockerfile from a fresh 3.5 project's `_server/Dockerfile`. The key changes from the 3.4 pattern are: + +- **Build from the project root**, not the server directory, so Dart workspaces resolve correctly: + + ```bash + $ docker build -f _server/Dockerfile . + ``` + +- Use **`dart build cli`** instead of `dart compile exe`: + + ```dockerfile + RUN dart build cli --target bin/main.dart --output build + ``` + +- **Copy the bundle directory**, not a single executable. The bundle contains `bin/main` and `lib/*` (the native libraries): + + ```dockerfile + COPY --from=build /app/_server/build/bundle/ ./ + ``` + +- **Update ENTRYPOINT** to point at the bundled binary: + + ```dockerfile + ENTRYPOINT ./bin/server --mode=$runmode --server-id=$serverid --logging=$logging --role=$role + ``` + +- **Bump the Dart SDK base image** to 3.10.x or newer: + + ```dockerfile + FROM dart:3.10.3 AS build + ``` -The embedded Postgres is a development convenience and does not run in production. Use a managed Postgres for your deployed server: [Serverpod Cloud](/cloud) provisions one for you automatically, or you can connect to a managed service like Cloud SQL or RDS. ## What's new in 3.5 @@ -155,18 +210,11 @@ The embedded Postgres is a development convenience and does not run in productio - **Health endpoints** on the built-in webserver. - **IDE and agent selection** in `serverpod create`. -### Migration concerns - -These are not new features but can affect existing 3.4 projects: - -- **`serverpod_database` package extraction.** Database types and helpers moved from `serverpod` into a new `serverpod_database` package. If you imported database APIs directly from `serverpod`, some of those imports now come from `serverpod_database`. The compiler will point out any imports that need updating after you run `dart pub upgrade`. -- **Logging revamp.** The logging API was reworked. If you have custom log handling, review your code against the new API. - ## Troubleshooting -### Port conflicts on `serverpod start` +### Port conflicts on startup -A previous `serverpod start` or a separate Postgres process may still be listening on 8090 or 8080. Stop the other process, or run on different ports. +Running more than one Serverpod server on the same machine can conflict on the default ports (8080 for the main server, 8090 for the database). This is a long-standing limitation, not specific to `serverpod start`. Stop the other server, or run on different ports. ### Agent skills aren't picked up after install From fe942b72099ce52320b94c7fa461fc3fbb8ae75b Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Tue, 2 Jun 2026 09:16:58 +0100 Subject: [PATCH 5/8] docs: Fix MD012 multiple blank lines --- docs/11-upgrading/01-upgrade-to-three-five.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/11-upgrading/01-upgrade-to-three-five.md b/docs/11-upgrading/01-upgrade-to-three-five.md index b3a99768..6fcb8bde 100644 --- a/docs/11-upgrading/01-upgrade-to-three-five.md +++ b/docs/11-upgrading/01-upgrade-to-three-five.md @@ -193,7 +193,6 @@ The fastest fix is to copy the updated Dockerfile from a fresh 3.5 project's `

Date: Wed, 3 Jun 2026 11:22:02 +0100 Subject: [PATCH 6/8] docs: Address review feedback on the 3.5 upgrade guide --- docs/11-upgrading/01-upgrade-to-three-five.md | 44 ++++--------------- 1 file changed, 9 insertions(+), 35 deletions(-) diff --git a/docs/11-upgrading/01-upgrade-to-three-five.md b/docs/11-upgrading/01-upgrade-to-three-five.md index 6fcb8bde..e3741bc1 100644 --- a/docs/11-upgrading/01-upgrade-to-three-five.md +++ b/docs/11-upgrading/01-upgrade-to-three-five.md @@ -91,7 +91,7 @@ If you've been developing against a Docker Postgres on 3.4, you can keep it with $ serverpod start --docker ``` -`serverpod start --docker` will start Docker for you if it isn't running, and will tear down the compose stack on exit if it was the one that started it. +With `--docker`, `serverpod start` brings up Docker if it isn't running, and tears down the compose stack on exit if the command brought it up. #### Switch to the embedded Postgres (recommended for new development) @@ -127,7 +127,7 @@ Once `dataPath` is set, `serverpod start` uses the embedded Postgres automatical $ serverpod start ``` -`dataPath` belongs in `development.yaml` and `testing.yaml` only. For production, use a managed Postgres: [Serverpod Cloud](/cloud) provisions one for you, or you can connect to a managed service like Cloud SQL or RDS. Do not add `dataPath` to `production.yaml` or `staging.yaml`. +The `dataPath` setting belongs in `development.yaml` and `testing.yaml` only. For production, use a managed Postgres: [Serverpod Cloud](/cloud) provisions one for you, or you can connect to a managed service like Cloud SQL or RDS. Do not add `dataPath` to `production.yaml` or `staging.yaml`. :::warning @@ -139,7 +139,7 @@ If you've added `dataPath` to your config and also pass `--docker`, the server c The first run compiles the native build hooks (this can take about 30 seconds) and applies the migration you generated above. The server then starts and watches your project; saving a file hot-reloads the code. -`serverpod start` also launches your Flutter app, in Chrome by default. Pass `--flutter-device ` to target a different device. For IDE debugging, projects scaffolded with 3.5 include a `launch.json` that runs `serverpod start` with the debugger attached; you can copy that file into your existing project from a fresh 3.5 scaffold if you want the same setup. +Beyond the server, `serverpod start` also launches the project's Flutter app. By default it uses Flutter's `web-server` device and opens your browser. Pass `--flutter-device ` to target a specific device. For IDE debugging, projects scaffolded with 3.5 include a `launch.json` that runs `serverpod start` with the debugger attached; you can copy that file into your existing project from a fresh 3.5 scaffold if you want the same setup. ## Add the agent skills (optional) @@ -159,39 +159,9 @@ Replace `cursor` with the editor you use: `antigravity`, `claude`, `cline`, `cod ## Production deployment notes -Your production build needs to switch from `dart compile exe` to `dart build cli`. The 3.5 server includes native build hooks that `dart compile` doesn't support. The new build produces a bundle (executable plus its native libraries) rather than a single static binary, so your Dockerfile needs a few updates. +Your production build needs to switch from `dart compile exe` to `dart build cli`. The 3.5 server includes native build hooks that `dart compile` doesn't support, and produces a bundle (executable plus its native libraries) rather than a single static binary, so your Dockerfile needs a few updates. -The fastest fix is to copy the updated Dockerfile from a fresh 3.5 project's `_server/Dockerfile`. The key changes from the 3.4 pattern are: - -- **Build from the project root**, not the server directory, so Dart workspaces resolve correctly: - - ```bash - $ docker build -f _server/Dockerfile . - ``` - -- Use **`dart build cli`** instead of `dart compile exe`: - - ```dockerfile - RUN dart build cli --target bin/main.dart --output build - ``` - -- **Copy the bundle directory**, not a single executable. The bundle contains `bin/main` and `lib/*` (the native libraries): - - ```dockerfile - COPY --from=build /app/_server/build/bundle/ ./ - ``` - -- **Update ENTRYPOINT** to point at the bundled binary: - - ```dockerfile - ENTRYPOINT ./bin/server --mode=$runmode --server-id=$serverid --logging=$logging --role=$role - ``` - -- **Bump the Dart SDK base image** to 3.10.x or newer: - - ```dockerfile - FROM dart:3.10.3 AS build - ``` +Copy the updated Dockerfile from the [3.5 framework template](https://github.com/serverpod/serverpod/blob/main/templates/serverpod_templates/projectname_server/Dockerfile) or a fresh 3.5 project's `_server/Dockerfile`. The key changes vs. the 3.4 pattern: build from the project root (not the server directory), copy the bundle directory, update `ENTRYPOINT` to point at the bundled binary, and bump the Dart SDK base image to 3.10.x or newer. ## What's new in 3.5 @@ -219,6 +189,10 @@ Running more than one Serverpod server on the same machine can conflict on the d Run `skills get` again from the project's root folder. Some editors, like Cursor, require enabling the MCP server in their settings. +## Still stuck? + +If something here didn't go as expected, reach out on the [community page](../support). + ## Related - [Migrations](../06-concepts/06-database/11-migrations.md): how Serverpod's migration system works under the hood. From 28b865a3e211b1553fdc7e55d8d44153414cca78 Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Wed, 3 Jun 2026 17:15:14 +0100 Subject: [PATCH 7/8] docs: Switch Related links to slug form --- docs/11-upgrading/01-upgrade-to-three-five.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/11-upgrading/01-upgrade-to-three-five.md b/docs/11-upgrading/01-upgrade-to-three-five.md index e3741bc1..04b73831 100644 --- a/docs/11-upgrading/01-upgrade-to-three-five.md +++ b/docs/11-upgrading/01-upgrade-to-three-five.md @@ -195,5 +195,5 @@ If something here didn't go as expected, reach out on the [community page](../su ## Related -- [Migrations](../06-concepts/06-database/11-migrations.md): how Serverpod's migration system works under the hood. -- [Build your first app](../05-build-your-first-app/01-creating-endpoints.md): the hands-on tour of the 3.5 workflow if you want to see `serverpod start` from scratch. +- [Migrations](../concepts/database/migrations): how Serverpod's migration system works under the hood. +- [Build your first app](../get-started/creating-endpoints): the hands-on tour of the 3.5 workflow if you want to see `serverpod start` from scratch. From 37d4301055291ff7cca6669f5db31e8e99e9621c Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Wed, 3 Jun 2026 17:29:27 +0100 Subject: [PATCH 8/8] docs: Switch archived pgvector guide's Migrations link to slug form --- docs/11-upgrading/02-archive/05-upgrade-to-pgvector.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/11-upgrading/02-archive/05-upgrade-to-pgvector.md b/docs/11-upgrading/02-archive/05-upgrade-to-pgvector.md index 5c51361d..4156eb99 100644 --- a/docs/11-upgrading/02-archive/05-upgrade-to-pgvector.md +++ b/docs/11-upgrading/02-archive/05-upgrade-to-pgvector.md @@ -68,7 +68,7 @@ $ serverpod create-migration $ dart run bin/main.dart --apply-migrations ``` -For more details on creating and applying migrations, see the [Migrations](../../06-concepts/06-database/11-migrations.md) page. +For more details on creating and applying migrations, see the [Migrations](../../concepts/database/migrations) page. The pgvector extension will be automatically enabled during the first migration that includes a vector column.