Skip to content

docs: Clarify how migrations are applied with serverpod start #599

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Zfinix wants to merge 2 commits into
base: main
Choose a base branch
from
+10 −1
Open

docs: Clarify how migrations are applied with serverpod start #599

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
201a137
docs: Clarify how migrations are applied with serverpod start
Zfinix Jun 12, 2026
c2087b8
docs: Make the apply migrations section scannable
Zfinix Jun 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/06-concepts/06-database/11-migrations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,9 @@ For each migration, five files are created:

## Apply migrations

Migrations are applied using the server runtime. To apply migrations, navigate to your project's `server` package directory, then start the server with the `--apply-migrations` flag. Migrations are applied as part of the startup sequence and the framework asserts that each migration is only applied once to the database.
During local development, `serverpod start` applies your migrations for you: pending migrations run on the first boot, and you can apply new ones at any time by pressing **A** in the terminal UI.

@Swiftaxe Swiftaxe Jun 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: Users scan documentation real quick. When scanning quickly, the text "pressing A" disappears and what stands out is the "dart run bin/main.dart...". Consider following the pattern in the "Build your first app", where Press R stands out by using a bullet.

Image

The same goes for "production and automated pipeline" which disappears in text. Consider if this should be a heading, to catch the attention of users searching for those particular use cases.

@Zfinix Zfinix Jun 15, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done, split it into During development (bullets so A stands out) and In production or CI headings.


To apply migrations explicitly, for example in production or an automated pipeline, start the server runtime with the `--apply-migrations` flag from your `server` package directory. Migrations are applied as part of the startup sequence and the framework asserts that each migration is only applied once to the database.

```bash
$ dart run bin/main.dart --apply-migrations
Expand Down
Loading