Update for FastAPI <> Next.js alignment

docs/intro/quickstart/connecting/fastapi.rst

@@ -10,21 +10,22 @@ Connecting to the database
 
   .. note::
 
-    Notice that the ``create_client`` function isn't being passed any connection details. How does Gel know how to connect to the database you set up earlier? When we ran ``gel project init`` earlier, the CLI created credentials for the local database and stored them in a well-known location. When you initialize your client with ``create_client()``, Gel will check the places it knows about for connection details.
-
-    With Gel, you do not need to come up with your own scheme for how to build the correct database connection credentials and worry about leaking them into your code. You simply use Gel "projects" for local development, and set the appropriate environment variables when you're ready to deploy, and the client knows what to do!
+    Notice that the ``create_async_client`` function isn't being passed any connection details. With |Gel|, you do not need to come up with your own scheme for how to build the correct database connection credentials and worry about leaking them into your code. You simply use |Gel| "projects" for local development, and set the appropriate environment variables in your deployment environments, and the ``create_async_client`` function knows what to do!
 
   .. edb:split-point::
 
   .. code-block:: python
     :caption: ./test.py
 
     import gel
+    import asyncio
 
-    client = gel.create_async_client()
+    async def main():
+        client = gel.create_async_client()
+        result = await client.query_single("select 'Hello from Gel!';")
+        print(result)
 
-    result = client.query_single("select 'Hello from Gel!';")
-    print(result)
+    asyncio.run(main())
 
   .. code-block:: sh
 
@@ -41,31 +42,33 @@ Connecting to the database
     :caption: ./test.py
 
       import gel
-
-      client = gel.create_async_client()
-
-    - result = client.query_single("select 'Hello from Gel!';")
-    - print(result)
-    + client.query("""
-    +     insert Deck { name := "I am one" }
-    + """)
+      import asyncio
+
+      async def main():
+          client = gel.create_async_client()
+    -     result = await client.query_single("select 'Hello from Gel!';")
+    -     print(result)
+    +     await client.query("""
+    +         insert Deck { name := "I am one" }
+    +     """)
     +
-    + client.query("""
-    +     insert Deck { name := "I am two" }
-    + """)
+    +     await client.query("""
+    +         insert Deck { name := "I am two" }
+    +     """)
     +
-    + decks = client.query("""
-    +     select Deck {
-    +         id,
-    +         name
-    +     }
-    + """)
+    +     decks = await client.query("""
+    +         select Deck {
+    +             id,
+    +             name
+    +         }
+    +     """)
     +
-    + for deck in decks:
-    +     print(f"ID: {deck.id}, Name: {deck.name}")
+    +     for deck in decks:
+    +         print(f"ID: {deck.id}, Name: {deck.name}")
     +
-    + client.query("delete Deck")
+    +     await client.query("delete Deck")
 
+      asyncio.run(main())
 
   .. code-block:: sh
 

docs/intro/quickstart/connecting/index.rst

@@ -1,8 +1,8 @@
 .. edb:env-switcher::
 
-==========
-Connecting
-==========
+==========================
+Connecting to the database
+==========================
 
 .. toctree::
   :maxdepth: 3

docs/intro/quickstart/inheritance/fastapi.rst

@@ -85,6 +85,6 @@ Adding shared properties
                       order by .order
                   )
               }
-    +         order by .updated_at DESC
+    +         order by .updated_at desc
           """)
           return decks

docs/intro/quickstart/inheritance/index.rst

@@ -1,8 +1,8 @@
 .. edb:env-switcher::
 
-===========
-Inheritance
-===========
+========================
+Adding shared properties
+========================
 
 .. toctree::
   :maxdepth: 3

docs/intro/quickstart/modeling/fastapi.rst

@@ -6,16 +6,15 @@ Modeling the data
 
 .. edb:split-section::
 
-  The flashcards application has a simple data model, but it's interesting enough to get a taste of many of the features of the Gel schema language. You have a ``Card`` class that extends the ``CardBase`` class describing a single flashcard, which for now contains two required string properties: ``front`` and ``back``. Each ``Card`` belongs to a ``Deck``, and there is an explicit ordering to the cards in a given deck.
+  The flashcards application has a simple data model, but it's interesting enough to utilize many unique features of the |Gel| schema language.
 
-  Looking at the mock data, you can see this structure in the JSON.
+  Looking at the mock data in the example JSON file ``./deck-edgeql.json``, you can see this structure in the JSON. There is a ``Card`` class that describes a single flashcard, which contains two required string properties: ``front`` and ``back``. Each ``Deck`` object has zero or more ``Card`` objects in a list.
 
-  .. code-block:: typescript
+  .. code-block:: python
 
     from pydantic import BaseModel
 
     class CardBase(BaseModel):
-      order: int
       front: str
       back: str
 
@@ -62,30 +61,34 @@ Modeling the data
 
   Congratulations! This first version of the data model's schema is *stored in a file on disk*. Now you need to signal the database to actually create types for ``Deck`` and ``Card`` in the database.
 
-  To make Gel do that, you need to do two quick steps:
+  To make |Gel| do that, you need to do two quick steps:
 
-  * **Create a migration**: a file with a list of low-level instructions.
+  1. **Create a migration**: a "migration" is a file containing a set of low level instructions that define how the database schema should change. It records any additions, modifications, or deletions to your schema in a way that the database can understand.
 
-    .. note::
+     .. note::
 
-      When you are changing existing schema, the CLI migration tool might ask questions to ensure that it understands your changes exactly. Since the existing schema was empty, the CLI will skip asking any questions and simply create the migration file.
+       When you are changing existing schema, the CLI migration tool might ask questions to ensure that it understands your changes exactly. Since the existing schema was empty, the CLI will skip asking any questions and simply create the migration file.
 
-  * **Apply the migration**: basically, tell Gel "I want you to use these instructions and get my types ready for action."
+  2. **Apply the migration**: This executes the migration file on the database, instructing |Gel| to implement the recorded changes in the database. Essentially, this step updates the database structure to match your defined schema, ensuring that the ``Deck`` and ``Card`` types are created and ready for use.
 
   .. code-block:: sh
 
-      $ gel migration create
-      Created ./dbschema/migrations/00001-m125ajr.edgeql, id: m125ajrbqp7ov36s7aniefxc376ofxdlketzspy4yddd3hrh4lxmla
-      $ gel migrate
-      Applying m125ajrbqp7ov36s7aniefxc376ofxdlketzspy4yddd3hrh4lxmla (00001-m125ajr.edgeql)
-      ... parsed
-      ... applied
+    $ uvx gel migration create
+    Created ./dbschema/migrations/00001-m125ajr.edgeql, id: m125ajrbqp7ov36s7aniefxc376ofxdlketzspy4yddd3hrh4lxmla
+    $ uvx gel migrate
+    Applying m125ajrbqp7ov36s7aniefxc376ofxdlketzspy4yddd3hrh4lxmla (00001-m125ajr.edgeql)
+    ... parsed
+    ... applied
 
 
 .. edb:split-section::
 
   Take a look at the schema you've generated in the built-in database UI. Use this tool to visualize your data model and see the object types and links you've defined.
 
+  .. edb:split-point::
+
   .. code-block:: sh
 
-      $ gel ui
+    $ uvx gel ui
+
+  .. image:: images/schema-ui.png

docs/intro/quickstart/modeling/index.rst

@@ -1,8 +1,8 @@
 .. edb:env-switcher::
 
-========
-Modeling
-========
+=================
+Modeling the data
+=================
 
 .. toctree::
   :maxdepth: 3

docs/intro/quickstart/modeling/nextjs.rst

@@ -8,7 +8,7 @@ Modeling the data
 
   The flashcards application has a simple data model, but it's interesting enough to utilize many unique features of the |Gel| schema language.
 
-  Looking at the mock data in our example JSON file ``./deck-edgeql.json``, you can see this structure in the JSON. There is a ``Card`` type that describes a single flashcard, which contains two required string properties: ``front`` and ``back``. Each ``Deck`` object has a link to zero or more ``Card`` objects in an array.
+  Looking at the mock data in the example JSON file ``./deck-edgeql.json``, you can see this structure in the JSON. There is a ``Card`` type that describes a single flashcard, which contains two required string properties: ``front`` and ``back``. Each ``Deck`` object has zero or more ``Card`` objects in an array.
 
   .. code-block:: typescript
 

docs/intro/quickstart/overview/fastapi.rst

@@ -5,57 +5,54 @@ Quickstart
 ==========
 
 Welcome to the quickstart tutorial! In this tutorial, you will update a FastAPI
-backend for a Flashcards application to use Gel as your data layer. The
+backend for a Flashcards application to use |Gel| as your data layer. The
 application will let users build and manage their own study decks, with each
 flashcard featuring customizable text on both sides - making it perfect for
 studying, memorization practice, or creating educational games.
 
-Don't worry if you're new to Gel - you will be up and running with a working
-FastAPI backend and a local Gel database in just about **5 minutes**. From
-there, you will replace the static mock data with a Gel powered data layer in
+Don't worry if you're new to |Gel| - you will be up and running with a working
+FastAPI backend and a local |Gel| database in just about **5 minutes**. From
+there, you will replace the static mock data with a |Gel| powered data layer in
 roughly 30-45 minutes.
 
 By the end of this tutorial, you will be comfortable with:
 
--  Creating and updating a database schema
--  Running migrations to evolve your data
--  Writing EdgeQL queries
--  Building an app backed by Gel
+*  Creating and updating a database schema
+*  Running migrations to evolve your data
+*  Writing EdgeQL queries
+*  Building an app backed by |Gel|
 
-********************************
- Features of the flashcards app
-********************************
 
--  Create, edit, and delete decks
--  Add/remove cards with front/back content
--  Clean, type-safe schema with Gel
+Features of the flashcards app
+------------------------------
 
-**************
- Requirements
-**************
+*  Create, edit, and delete decks
+*  Add/remove cards with front/back content
+*  Clean, type-safe schema with |Gel|
+
+Requirements
+------------
 
 Before you start, you need:
 
--  Basic familiarity with Python and FastAPI
--  Python 3.8+ on a Unix-like OS (Linux, macOS, or WSL)
--  A code editor you love
+*  Basic familiarity with Python and FastAPI
+*  Python 3.8+ on a Unix-like OS (Linux, macOS, or WSL)
+*  A code editor you love
 
-**********************
- Why Gel for FastAPI?
-**********************
+Why |Gel| for FastAPI?
+----------------------
 
--  **Type Safety**: Catch data errors before runtime
--  **Rich Modeling**: Use object types and links to model relations
--  **Modern Tooling**: Python-friendly schemas and migrations
--  **Performance**: Efficient queries for complex data
--  **Developer Experience**: An intuitive query language (EdgeQL)
+*  **Type Safety**: Catch data errors before runtime
+*  **Rich Modeling**: Use object types and links to model relations
+*  **Modern Tooling**: Python-friendly schemas and migrations
+*  **Performance**: Efficient queries for complex data
+*  **Developer Experience**: An intuitive query language (EdgeQL)
 
-************
- Need Help?
-************
+Need Help?
+----------
 
 If you run into issues while following this tutorial:
 
--  Check the `Gel documentation <https://docs.geldata.com>`_
+-  Check the `|Gel| documentation <https://docs.geldata.com>`_
 -  Visit our `community Discord <https://discord.gg/gel>`_
 -  File an issue on `GitHub <https://github.com/geldata/gel>`_

docs/intro/quickstart/overview/index.rst

@@ -1,8 +1,8 @@
 .. edb:env-switcher::
 
-========
-Overview
-========
+==========
+Quickstart
+==========
 
 .. toctree::
   :maxdepth: 3

docs/intro/quickstart/setup/fastapi.rst

@@ -1,12 +1,12 @@
 .. _ref_quickstart_fastapi_setup:
 
-#############################
- Setting up your environment
-#############################
+===========================
+Setting up your environment
+===========================
 
 .. edb:split-section::
 
-  Use git to clone the Next.js starter template into a new directory called ``flashcards``. This will create a fully configured Next.js project and a local Gel instance with an empty schema. You will see the database instance being installed and the project being initialized. You are now ready to start building the application.
+  Use git to clone the `FastAPI starter template <https://github.com/geldata/quickstart-fastapi>`_ into a new directory called ``flashcards``. This will create a fully configured FastAPI project and a local |Gel| instance with an empty schema. You will see the database instance being created and the project being initialized. You are now ready to start building the application.
 
   .. code-block:: sh
 
@@ -17,31 +17,15 @@
     $ python -m venv venv
     $ source venv/bin/activate # or venv\Scripts\activate on Windows
     $ pip install -r requirements.txt
-
-.. edb:split-section::
-
-  Next, you need to install the Gel CLI. The Gel CLI is a tool that helps you manage your Gel project. You will use it to run migrations, generate code, and interact with the database.
-
-  .. code-block:: sh
-
-    $ curl --proto '=https' --tlsv1.2 -sSf https://sh.edgedb.com | sh
-
-.. edb:split-section::
-
-  Once you've installed the Gel CLI, you can initialize the project by running the following command from the project root. This will create a new Gel project instance in the current directory.
-
-
-  .. code-block:: sh
-
-    $ gel project init
+    $ uvx gel project init
 
 .. edb:split-section::
 
   Explore the empty database by starting our REPL from the project root.
 
   .. code-block:: sh
 
-    $ gel
+    $ uvx gel
 
 .. edb:split-section::
 
@@ -73,12 +57,26 @@
 
 .. edb:split-section::
 
-  Fun! You will create a proper data model for the application in the next step, but for now, take a look around the project we have. Here are the new files that integrate Gel:
+  Fun! You will create a proper data model for the application in the next step, but for now, take a look around the project we have. Here are the files that integrate |Gel|:
 
-  - ``gel.toml``: The configuration file for the Gel project instance.
+  - ``gel.toml``: The configuration file for the |Gel| project instance. Notice that we have a ``hooks.migration.apply.after`` hook that will run ``uvx gel-py`` after migrations are applied. This will run the code generator that you will use later to get fully type-safe queries you can run from your FastAPI backend. More details on that to come!
   - ``dbschema/``: This directory contains the schema for the database, and later supporting files like migrations, and generated code.
   - :dotgel:`dbschema/default`: The default schema file that you'll use to define your data model. It is empty for now, but you'll add your data model to this file in the next step.
 
-  .. code-block:: sh
+  .. tabs::
+
+    .. code-tab:: toml
+      :caption: gel.toml
+
+      [instance]
+      server-version = 6.0
+
+      [hooks]
+      schema.update.after = "uvx gel-py"
+
+    .. code-tab:: sdl
+      :caption: dbschema/default.gel
+
+      module default {
 
-    $ tree
+      }

docs/intro/quickstart/setup/index.rst

@@ -1,8 +1,8 @@
 .. edb:env-switcher::
 
-=====
-Setup
-=====
+===========================
+Setting up your environment
+===========================
 
 .. toctree::
   :maxdepth: 3