Skip to content

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

Open
Zfinix wants to merge 13 commits into
mainfrom
chore/migrate-self-hosted-database
Open

Zfinix wants to merge 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

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

3 participants