Add a Gel Cloud to self-hosted migration guide - #9132
Conversation
Docs preview deploy✅ Successfully deployed docs preview for commit 528d5ac: https://edgedb-docs-o1el8f7nu-edgedb.vercel.app (Last updated: Dec 23, 2025, 21:54:17 UTC) |
There was a problem hiding this comment.
Pull request overview
This PR adds a comprehensive migration guide to help users move their data from Gel Cloud to self-hosted Gel instances in preparation for Gel Cloud's sunset at the end of January 2026. The guide provides a phased approach with preparation steps, migration procedures, and post-migration verification.
Key Changes:
- New migration guide document with three-phase workflow (Preparation, Migration/Cutover, Verification)
- Documentation of both streaming and file-based migration approaches
- Integration of the new guide into the cloud documentation index
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
docs/cloud/migrate_from.rst |
New comprehensive migration guide covering deployment setup, data transfer methods, and post-migration steps |
docs/cloud/index.rst |
Added reference to the new migration guide in the documentation tree |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Update your application's configuration to point to the new instance. Replace | ||
| your :gelenv:`INSTANCE` and :gelenv:`SECRET_KEY` variables with the new | ||
| connection details: |
There was a problem hiding this comment.
The reference to ":gelenv:INSTANCE and :gelenv:SECRET_KEY" appears inconsistent with the connection details provided. The document primarily discusses DSN, TLS_CA, and CLIENT_TLS_SECURITY environment variables, but doesn't explain what INSTANCE or SECRET_KEY are or why they need to be replaced. Either these variables should be explained in the context of Gel Cloud configuration, or this reference should be removed if they're not relevant to the migration process.
| Update your application's configuration to point to the new instance. Replace | |
| your :gelenv:`INSTANCE` and :gelenv:`SECRET_KEY` variables with the new | |
| connection details: | |
| Update your application's configuration to point to the new instance. If your | |
| application currently uses the Gel Cloud environment variables | |
| :gelenv:`INSTANCE` and :gelenv:`SECRET_KEY`, update it to use the following | |
| self-hosted connection variables instead: |
| .. _ref_migrate_from: | ||
|
|
||
| ========================================== | ||
| Migrating from Gel Cloud to Self-Hosted |
There was a problem hiding this comment.
The document title indicates migration "from Gel Cloud to Self-Hosted" but the PR title suggests the opposite direction ("self-hosted to Gel Cloud migration guide"). Based on the content which describes moving data from Gel Cloud to a self-hosted instance, the document title appears correct while the PR title may be incorrect. However, this creates confusion - the title should match the actual migration direction being documented.
| * **TLS CA**: The certificate used to secure the connection (unless using a | ||
| public CA or ``--trust-tls-cert``). |
There was a problem hiding this comment.
The certificate location reference is unclear. The text states "The certificate used to secure the connection" but doesn't clarify where users obtain this certificate from their self-hosted deployment. Consider adding clarity about where to retrieve the TLS CA certificate for the new self-hosted instance.
| * **TLS CA**: The certificate used to secure the connection (unless using a | |
| public CA or ``--trust-tls-cert``). | |
| * **TLS CA**: The root certificate authority (CA) file for your self-hosted | |
| |Gel| instance, used to verify its TLS certificate. The relevant | |
| :ref:`self-hosted deployment guide <ref_guide_deployment>` explains where | |
| to download or copy this file for your setup (for example, as a ``ca.pem`` | |
| file from your control panel or container filesystem). You can omit this | |
| when using a public CA or ``--trust-tls-cert``. |
| $ gel dump --instance <org-name>/<instance-name> --all my_database_backup.gel | ||
|
|
||
| # 2. Restore from file | ||
| $ gel restore --dsn <new_self_hosted_dsn> --all my_database_backup.gel |
There was a problem hiding this comment.
The file extension ".gel" for the backup file is used without prior explanation or context about whether this is a required or conventional extension. Consider clarifying whether this extension is required by the tool or just a suggested naming convention.
scotttrinh
changed the title
This only works for a single branch, and it's safer to just have the intermediate file anyway, so let's remove a choice here.
No description provided.