Skip to content

docs: Add guide for migrating a self-hosted database to Cloud - #853

Merged
developerjamiu merged 13 commits into
mainfrom
chore/migrate-self-hosted-database
Sep 29, 2026
Merged

developerjamiu merged 13 commits into
mainfrom
chore/migrate-self-hosted-database

Conversation

@Zfinix

@Zfinix Zfinix commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Closes: serverpod/serverpod#5768
Closes: serverpod/serverpod#5769

Adds a guide for moving a self-hosted database (Serverpod and PostgreSQL in Docker, for example on a VPS) into a Cloud project. Nothing covers this today, and the obvious pg_dump and pg_restore --data-only route fails on the tables Cloud writes itself.

  • The dump is taken with --data-only at the source, which orders tables by foreign key. A full dump restored with --data-only fails on serverpod_auth_core_profile.
  • --exclude-table-data covers the data Cloud writes on each deploy, each pattern keeping a trailing * so the table's ID sequence is left out too.
  • emailSecretHashPepper and the JWT keys are copied before any user rows land, otherwise sign-in fails with invalidCredentials and the first refresh deletes the session.
  • Profile images take a two-pass restore, since serverpod_auth_core_profile and serverpod_auth_core_profile_image reference each other and the Cloud database user cannot disable triggers.
  • Four troubleshooting entries for the errors a missed step produces.

Every step run against a Cloud project on the starter plan, with a Docker Compose source on PostgreSQL 16, at Serverpod 4.0.0 and Cloud CLI 1.0.0.

image

@Zfinix Zfinix self-assigned this Sep 21, 2026
@SandPod
SandPod requested a review from Isakdl September 21, 2026 07:32
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Zfinix and others added 6 commits September 24, 2026 09:56
Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com>
Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com>
Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com>
Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com>
Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com>
Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com>

@Isakdl Isakdl left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Very cool to get this in, I got some suggestions here and there.

Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated
Comment thread cloud_docs/guides/migrate-a-self-hosted-database.md Outdated

@developerjamiu developerjamiu left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

One last comment

@developerjamiu

Copy link
Copy Markdown
Contributor

@Isakdl all your threads are addressed; could you take another look?

@Isakdl Isakdl left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

LGTM

@developerjamiu
developerjamiu merged commit e26a607 into main Sep 29, 2026
7 checks passed
@developerjamiu
developerjamiu deleted the chore/migrate-self-hosted-database branch September 29, 2026 08:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

3 participants