Skip to content

Commit 8519106

Browse files
scotttrinhscotttrinh
authored
Add a Gel Cloud to self-hosted migration guide (#9132)
1 parent ba406fa commit 8519106

File tree

8 files changed

+681
-111
lines changed

8 files changed

+681
-111
lines changed

‎docs/cloud/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Cloud
1919
deploy/fly
2020
deploy/render
2121
deploy/railway
22+
migrate_from
2223

2324

2425
|Gel| Cloud is a fully managed, effortless cloud database service,

‎docs/cloud/migrate_from.rst‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
.. _ref_migrate_from:
2+
3+
=======================================
4+
Migrating from Gel Cloud to Self-Hosted
5+
=======================================
6+
7+
:edb-alt-title: Migrating from Gel Cloud to Self-Hosted Gel
8+
9+
|Gel| Cloud is sunsetting at the end of January 2026. To ensure your
10+
applications continue to run smoothly, you should migrate your data to a
11+
self-hosted |Gel| instance.
12+
13+
This guide outlines the process of migrating your production data. We strongly
14+
recommend performing a "dry run" with your staging or development environment
15+
first to familiarize yourself with the workflow.
16+
17+
18+
Phase 1: Preparation
19+
====================
20+
21+
1. Spin up your self-hosted deployment
22+
--------------------------------------
23+
24+
While you can host |Gel| on any infrastructure that supports Docker or binary
25+
installations, we recommend using a managed cloud provider (such as Fly.io,
26+
AWS, or GCP with managed Postgres) for production reliability.
27+
28+
See our :ref:`self-hosted deployment guides <ref_guide_deployment>` for
29+
step-by-step instructions on deploying to various platforms.
30+
31+
Ensure your new instance is:
32+
33+
* Running the same version of |Gel| as your Cloud instance (or newer).
34+
* Configured with a persistent volume for data or connected to a managed
35+
Postgres instance.
36+
37+
2. Retrieve connection parameters
38+
---------------------------------
39+
40+
Once your new instance is live, you need its DSN (Data Source Name) or
41+
individual connection parameters. Each :ref:`deployment guide
42+
<ref_guide_deployment>` outlines the best way to retrieve the various
43+
connection parameters from your specific setup. You will typically need:
44+
45+
* **Host**: The domain or IP of your new instance.
46+
* **Port**: Default is ``5656``.
47+
* **User**: Default is |admin|.
48+
* **Password**: The password you set during initialization.
49+
* **TLS CA**: The certificate used to secure the connection (unless using a
50+
public CA or ``--trust-tls-cert``).
51+
52+
The DSN format is:
53+
54+
.. code-block:: text
55+
56+
gel://<user>:<password>@<host>:<port>/<branch>
57+
58+
All components except the scheme are optional. See :ref:`ref_reference_connection_dsn`
59+
for more details.
60+
61+
62+
Phase 2: The Migration (Cutover)
63+
================================
64+
65+
To ensure data consistency, you must prevent new writes to your database
66+
during the transfer.
67+
68+
1. Enable maintenance mode
69+
--------------------------
70+
71+
Before touching the data, put your application into maintenance mode. This
72+
ensures that no new records are created in |Gel| Cloud after you've started
73+
the dump.
74+
75+
* **Web Apps**: Point your load balancer to a static "Maintenance" page.
76+
* **Background Jobs**: Stop all workers, cron jobs, or queues that interact
77+
with the database.
78+
79+
2. Perform the migration
80+
------------------------
81+
82+
You can use the |Gel| CLI to move data directly from your Cloud instance to
83+
your new self-hosted instance.
84+
85+
.. code-block:: bash
86+
87+
# 1. Dump from Gel Cloud to directory
88+
$ gel dump --instance <org-name>/<instance-name> \
89+
--all --format=dir \
90+
production_dump
91+
92+
# 2. Restore to self-hosted from dump
93+
$ gel restore --dsn <new_self_hosted_dsn> --all production_dump
94+
95+
.. note::
96+
97+
If your self-hosted instance uses a self-signed TLS certificate, you may
98+
need to add ``--tls-security insecure`` to the restore command, or first
99+
retrieve the TLS certificate and set it via :gelenv:`TLS_CA`.
100+
101+
102+
Phase 3: Verification and Go-Live
103+
=================================
104+
105+
1. Update application environment variables
106+
-------------------------------------------
107+
108+
Update your application's configuration to point to the new instance. Replace
109+
the Gel Cloud specific connection environment variables :gelenv:`INSTANCE` and
110+
:gelenv:`SECRET_KEY` variables with the new connection details:
111+
112+
* :gelenv:`DSN`: :geluri:`user:password@host:port/branch`
113+
* :gelenv:`TLS_CA`: The TLS certificate content (if your instance uses a
114+
self-signed certificate)
115+
* :gelenv:`CLIENT_TLS_SECURITY`: Set to ``insecure`` if you need to skip TLS
116+
verification (not recommended for production)
117+
118+
2. Sanity check
119+
---------------
120+
121+
Before turning off maintenance mode:
122+
123+
* Run a few :gelcmd:`query` commands against the new instance to verify data
124+
integrity.
125+
* Check that your schema migrated correctly: :gelcmd:`migrate --status`.
126+
* Launch a local instance of your app connected to the new production DB to
127+
ensure connection logic is sound.
128+
129+
3. Disable maintenance mode
130+
---------------------------
131+
132+
Once verified, restart your application servers and background workers.
133+
Monitor your logs closely for any connection or permission errors.
134+
135+
136+
Post-Migration Note
137+
===================
138+
139+
Once you are 100% certain your data is safe and your app is stable on the new
140+
host, you can de-provision your |Gel| Cloud instance. Remember that all |Gel|
141+
Cloud data will be deleted after the January 2026 deadline.

‎docs/reference/running/deployment/aws_aurora_ecs.rst‎

Lines changed: 99 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -79,32 +79,6 @@ has been assigned to your Gel instance:
7979
8080
.. lint-on
8181
82-
It's often convenient to create an alias for the remote instance using
83-
:gelcmd:`instance link`.
84-
85-
.. code-block:: bash
86-
87-
$ gel instance link \
88-
--trust-tls-cert \
89-
--dsn gel://admin:<password>@<hostname> \
90-
my_aws_instance
91-
92-
This aliases the remote instance to ``my_aws_instance`` (this name can be
93-
anything). You can now use the ``-I my_aws_instance`` flag to run CLI commands
94-
against this instance, as with local instances.
95-
96-
.. note::
97-
98-
The command groups :gelcmd:`instance` and :gelcmd:`project` are not
99-
intended to manage production instances.
100-
101-
.. code-block:: bash
102-
103-
$ gel -I my_aws_instance
104-
Gel x.x
105-
Type \help for help, \quit to quit.
106-
gel>
107-
10882
To make changes to your Gel deployment like upgrading the Gel version or
10983
enabling the UI you can follow the CloudFormation
11084
`Updating a stack <stack-update_>`_ instructions. Search for
@@ -143,6 +117,105 @@ your terminal:
143117
/AWSCloudFormation/latest/UserGuide/cfn-whatis-howdoesitwork.html
144118
.. _docker-tags: https://hub.docker.com/r/geldata/gel/tags
145119

120+
121+
Connecting your application
122+
===========================
123+
124+
To connect your application to the Gel instance, you'll need to provide
125+
connection parameters. Gel client libraries can be configured using either
126+
a DSN (connection string) or individual environment variables.
127+
128+
Obtaining connection parameters
129+
-------------------------------
130+
131+
Your connection requires the following components:
132+
133+
- **Host**: The ``PublicHostname`` value from the CloudFormation Stack's
134+
``Outputs`` tab.
135+
- **Port**: ``5656`` (the default Gel port)
136+
- **Username**: |admin| (the default superuser)
137+
- **Password**: The ``SuperUserPassword`` you specified during deployment
138+
- **Branch**: |main| (the default branch)
139+
140+
Construct the DSN using these values:
141+
142+
.. code-block:: bash
143+
144+
$ GEL_DSN="gel://admin:<password>@<hostname>:5656"
145+
146+
Obtaining the TLS certificate
147+
-----------------------------
148+
149+
.. warning::
150+
151+
The CloudFormation template does not configure TLS certificates correctly.
152+
We recommend using ``--tls-security insecure`` for testing, but for
153+
production you should use our `helm chart <helm-chart_>`_ or configure
154+
TLS manually.
155+
156+
To connect securely, your application needs the server's TLS certificate.
157+
For self-signed certificates, you can retrieve the certificate by connecting
158+
to the instance and extracting it:
159+
160+
.. code-block:: bash
161+
162+
$ gel --dsn $GEL_DSN --tls-security insecure \
163+
query "SELECT sys::get_tls_certificate()"
164+
165+
Store this certificate and provide it to your application via the
166+
:gelenv:`TLS_CA` or :gelenv:`TLS_CA_FILE` environment variable.
167+
168+
Using in your application
169+
-------------------------
170+
171+
Set these environment variables where you deploy your application:
172+
173+
.. code-block:: bash
174+
175+
GEL_DSN="gel://admin:<password>@<hostname>:5656"
176+
# For self-signed certificates:
177+
GEL_CLIENT_TLS_SECURITY=insecure
178+
# Or with a proper TLS certificate:
179+
GEL_TLS_CA="<certificate content>"
180+
181+
Gel's client libraries will automatically read these environment variables.
182+
183+
Local development with the CLI
184+
------------------------------
185+
186+
To make your remote instance easier to work with during local development,
187+
create an alias using :gelcmd:`instance link`.
188+
189+
.. note::
190+
191+
The command groups :gelcmd:`instance` and :gelcmd:`project` are not
192+
intended to manage production instances.
193+
194+
.. code-block:: bash
195+
196+
$ gel instance link \
197+
--dsn $GEL_DSN \
198+
--non-interactive \
199+
--trust-tls-cert \
200+
my_aws_instance
201+
202+
You can now refer to the remote instance using the alias ``my_aws_instance``.
203+
Use this alias wherever an instance name is expected:
204+
205+
.. code-block:: bash
206+
207+
$ gel -I my_aws_instance
208+
Gel x.x
209+
Type \help for help, \quit to quit.
210+
gel>
211+
212+
Or apply migrations:
213+
214+
.. code-block:: bash
215+
216+
$ gel -I my_aws_instance migrate
217+
218+
146219
Health Checks
147220
=============
148221

0 commit comments

Comments
 (0)