Merge branch 'new-gel-docs' into fastapi-quickstart

geldata · Feb 20, 2025 · 6ca8eeb · 6ca8eeb
2 parents 4a73306 + 02c6d9f
commit 6ca8eeb
Show file tree

Hide file tree

Showing 29 changed files with 465 additions and 240 deletions.
diff --git a/docs/guides/auth/built_in_ui.rst → docs/auth/built_in_ui.rst b/docs/guides/auth/built_in_ui.rst → docs/auth/built_in_ui.rst
diff --git a/docs/guides/auth/email_password.rst → docs/auth/email_password.rst b/docs/guides/auth/email_password.rst → docs/auth/email_password.rst
diff --git a/docs/guides/auth/images/ui-auth.png → docs/auth/images/ui-auth.png b/docs/guides/auth/images/ui-auth.png → docs/auth/images/ui-auth.png
diff --git a/docs/guides/auth/index.rst → docs/auth/index.rst b/docs/guides/auth/index.rst → docs/auth/index.rst
diff --git a/docs/guides/auth/magic_link.rst → docs/auth/magic_link.rst b/docs/guides/auth/magic_link.rst → docs/auth/magic_link.rst
diff --git a/docs/guides/auth/oauth.rst → docs/auth/oauth.rst b/docs/guides/auth/oauth.rst → docs/auth/oauth.rst
diff --git a/docs/guides/auth/webauthn.rst → docs/auth/webauthn.rst b/docs/guides/auth/webauthn.rst → docs/auth/webauthn.rst
diff --git a/docs/changelog/index.rst b/docs/changelog/index.rst
@@ -1,4 +1,3 @@
-.. eql:section-intro-page:: changelog
 
 =========
 Changelog

diff --git a/docs/cli/index.rst b/docs/cli/index.rst
@@ -1,5 +1,3 @@
-.. eql:section-intro-page:: cli
-
 .. _ref_cli_overview:
 
 ===

diff --git a/docs/clients/graphql/index.rst b/docs/clients/graphql/index.rst
@@ -1,5 +1,3 @@
-.. eql:section-intro-page:: graphql
-
 .. _ref_graphql_index:
 
 =======

diff --git a/docs/clients/index.rst b/docs/clients/index.rst
@@ -1,5 +1,3 @@
-.. eql:section-intro-page:: clients
-
 .. _ref_clients_index:
 
 ================

diff --git a/docs/cloud/index.rst b/docs/cloud/index.rst
@@ -6,13 +6,6 @@ Cloud
 
 :edb-alt-title: Using Gel Cloud
 
-|Gel| Cloud is the easiest way to host your Gel instance. We offer two ways
-to interact with Gel Cloud: via our CLI or through a graphical web
-interface nearly identical to the :ref:`Gel UI <ref_cli_gel_ui>`.
-
-.. edb:youtube-embed:: IG1MggUzzH4
-
-
 .. toctree::
     :maxdepth: 2
     :hidden:
@@ -28,10 +21,132 @@ interface nearly identical to the :ref:`Gel UI <ref_cli_gel_ui>`.
     deploy/railway
 
 
+|Gel| Cloud is a fully managed, effortless cloud database service,
+engineered to let you deploy your database instantly and connect from
+anywhere with near-zero configuration.
+
+Connecting your app
+===================
+
+Try a guide for connecting your app running on your platform of choice:
+
+.. TODO: render these with icons
+
+* :ref:`Vercel <ref_guide_cloud_deploy_vercel>`
+* :ref:`Netlify <ref_guide_cloud_deploy_netlify>`
+* :ref:`Fly.io <ref_guide_cloud_deploy_fly>`
+* :ref:`Render <ref_guide_cloud_deploy_render>`
+* :ref:`Railway <ref_guide_cloud_deploy_railway>`
+
+To connect your apps running on other platforms, generate a dedicated
+secret key for your instance with :gelcmd:`cloud secretkey create` or via the
+web UI's “Secret Keys” pane in your instance dashboard. Create two environment
+variables accessible to your production application:
+
+* :gelenv:`SECRET_KEY` - contains the secret key you generated
+* :gelenv:`INSTANCE` - the name of your |Gel| Cloud instance (``<org-name>/<instance-name>``)
+
+.. edb:youtube-embed:: IG1MggUzzH4
+
+
+Two ways to use Gel Cloud
+=========================
+
+1. CLI
+^^^^^^
+
+Log in to |Gel| Cloud via the CLI:
+
+.. code-block:: bash
+
+  $ gel cloud login
+
+
+This will open a browser window and allow you to log in via GitHub.
+Now, create your |Gel| Cloud instance the same way you would create a
+local instance:
+
+.. code-block:: bash
+
+  $ gel instance create <org-name>/<instance-name>
+
+or
+
+.. code-block:: bash
+
+  $ gel project init \
+  --server-instance <org-name>/<instance-name>
+
+
+2. GUI
+^^^^^^
+
+Create your instance at `cloud.geldata.com <https://cloud.geldata.com>`_ by
+clicking on “Create new instance” in the “Instances” tab.
+
+.. <div className={styles.cloudGuiImg} />
+
+Complete the following form to configure your instance. You can access
+your instance via the CLI using the name ``<org-name>/<instance-name>`` or via the GUI.
+
+
+Useful Gel Cloud commands
+=========================
+
+Get REPL
+^^^^^^^^
+
+.. code-block:: bash
+
+  $ gel \
+    -I <org-name>/<instance-name>
+
+Run migrations
+^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+  $ gel migrate \
+    -I <org-name>/<instance-name>
+
+Update your instance
+^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+  $ gel instance upgrade \
+    --to-version <target-version> \
+    -I <org-name>/<instance-name>
+
+Manual full backup
+^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+  $ gel dump \
+    --all --format dir \
+    -I <org-name>/<instance-name> \
+    <local-dump-path>
+
+Full restore
+^^^^^^^^^^^^
+
+.. code-block:: bash
+
+  $ gel restore \
+    --all \
+    -I <org-name>/<instance-name> \
+    <local-dump-path>
+
+.. note::
+
+  Restoring works only to an empty database.
+
+
 Questions? Problems? Bugs?
 ==========================
 
-Thank you for helping us make the best way to host your Gel instances even
+Thank you for helping us make the best way to host your |Gel| instances even
 better!
 
 * Please join us on `our Discord <https://discord.gg/umUueND6ag>`_  to ask

diff --git a/docs/reference/admin/branches.rst → docs/datamodel/branches.rst b/docs/reference/admin/branches.rst → docs/datamodel/branches.rst
@@ -1,20 +1,38 @@
+.. _ref_datamodel_branches:
+.. _ref_datamodel_databases:
+
 .. versionadded:: 5.0
 
-.. _ref_admin_branches:
+========
+Branches
+========
+
+Gel's |branches| are equivalent to PostgreSQL's *databases* and map to
+them directly. Gel comes with tooling to help manage branches and build
+a development workflow around them. E.g. when developing locally you can
+map your Gel branches to your Git branches, and when using Gel Cloud and
+GitHub you can have a branch per PR.
+
 
-======
-Branch
-======
+CLI commands
+============
+
+Refer to the :ref:`gel branch <ref_cli_gel_branch>` command group for
+details on the CLI commands for managing branches.
 
-:edb-alt-title: Branches
 
+.. _ref_admin_branches:
+
+DDL commands
+============
 
-This section describes the administrative commands pertaining to
-:ref:`branches <ref_datamodel_branches>`.
+These are low-level commands that are used to create, alter, and drop branches.
+You can use them when experimenting in REPL, of if you want to create your own
+tools to manage Gel branches.
 
 
 Create empty branch
-===================
+-------------------
 
 :eql-statement:
 
@@ -25,13 +43,13 @@ Create a new branch without schema or data.
     create empty branch <name> ;
 
 Description
------------
+^^^^^^^^^^^
 
 The command ``create empty branch`` creates a new Gel branch without schema
 or data, aside from standard schemas.
 
-Examples
---------
+Example
+^^^^^^^
 
 Create a new empty branch:
 
@@ -41,24 +59,24 @@ Create a new empty branch:
 
 
 Create schema branch
-====================
+--------------------
 
 :eql-statement:
 
-Create a new branch copying the schema of an existing branch.
+Create a new branch copying the schema (without data)of an existing branch.
 
 .. eql:synopsis::
 
     create schema branch <newbranch> from <oldbranch> ;
 
 Description
------------
+^^^^^^^^^^^
 
 The command ``create schema branch`` creates a new Gel branch with schema
 copied from an already existing branch.
 
-Examples
---------
+Example
+^^^^^^^
 
 Create a new schema branch:
 
@@ -68,7 +86,7 @@ Create a new schema branch:
 
 
 Create data branch
-==================
+------------------
 
 :eql-statement:
 
@@ -79,13 +97,13 @@ Create a new branch copying the schema and data of an existing branch.
     create data branch <newbranch> from <oldbranch> ;
 
 Description
------------
+^^^^^^^^^^^
 
 The command ``create data branch`` creates a new Gel branch with schema and
 data copied from an already existing branch.
 
-Examples
---------
+Example
+^^^^^^^
 
 Create a new data branch:
 
@@ -95,7 +113,7 @@ Create a new data branch:
 
 
 Drop branch
-===========
+-----------
 
 :eql-statement:
 
@@ -106,7 +124,7 @@ Remove a branch.
     drop branch <name> ;
 
 Description
------------
+^^^^^^^^^^^
 
 The command ``drop branch`` removes an existing branch. It cannot be executed
 while there are existing connections to the target branch.
@@ -115,8 +133,8 @@ while there are existing connections to the target branch.
 
     Executing ``drop branch`` removes data permanently and cannot be undone.
 
-Examples
---------
+Example
+^^^^^^^
 
 Remove a branch:
 
@@ -126,7 +144,7 @@ Remove a branch:
 
 
 Alter branch
-============
+------------
 
 :eql-statement:
 
@@ -137,14 +155,14 @@ Rename a branch.
     alter branch <oldname> rename to <newname> ;
 
 Description
------------
+^^^^^^^^^^^
 
 The command ``alter branch … rename`` changes the name of an existing branch.
 It cannot be executed while there are existing connections to the target
 branch.
 
-Examples
---------
+Example
+^^^^^^^
 
 Rename a branch: