Some branches<>databases footwork

geldata · Feb 15, 2025 · 05d05e0 · 05d05e0
1 parent ffc182e
commit 05d05e0
Show file tree

Hide file tree

Showing 21 changed files with 86 additions and 72 deletions.
diff --git a/docs/ai/index.rst b/docs/ai/index.rst
@@ -85,7 +85,7 @@ You may alternatively configure a provider via EdgeQL:
 
 .. code-block:: edgeql
 
-    configure current database
+    configure current branch
     insert ext::ai::OpenAIProviderConfig {
       secret := 'sk-....',
     };

diff --git a/docs/ai/reference.rst b/docs/ai/reference.rst
@@ -63,7 +63,7 @@ via EdgeQL:
 
 .. code-block:: edgeql
 
-    configure current database
+    configure current branch
     insert ext::ai::OpenAIProviderConfig {
       secret := 'sk-....',
     };

diff --git a/docs/cheatsheets/repl.rst b/docs/cheatsheets/repl.rst
@@ -67,10 +67,10 @@ Commands
     * - ``\ds, \describe schema``
       - Describe the entire schema.
 
-    * - ``\list databases``
+    * - ``\list branches``
 
         ``alias: \l``
-      - List databases.
+      - List |branches|.
     * - ``\list scalars [-sI] [pattern]``
 
         ``alias: \ls``
@@ -101,10 +101,10 @@ Commands
       - List indexes.
 
     * - ``\dump <filename>``
-      - Dump the current database to file.
+      - Dump the current |branch| to file.
 
     * - ``\restore <filename>``
-      - Restore the database from a dump file.
+      - Restore the |branch| from a dump file.
 
     * - ``\s, \history``
       - Show query history
@@ -120,18 +120,18 @@ Commands
         Type ``\set`` to see all available settings.
 
     * - ``\c, \connect [<dbname>]``
-      - Connect to a particular database.
+      - Connect to a particular |branch|.
 
 
 Sample usage
 ^^^^^^^^^^^^
 
-List databases:
+List |branches|:
 
 .. code-block:: edgeql-repl
 
     db> \ls
-    List of databases:
+    List of branches:
       db
       tutorial
 
@@ -140,7 +140,7 @@ List databases:
 ----------
 
 
-Connect to a database:
+Connect to a |branch|:
 
 .. code-block:: edgeql-repl
 

diff --git a/docs/cli/gel.rst b/docs/cli/gel.rst
@@ -80,11 +80,6 @@ Options
     Defaults to the value of the :gelenv:`USER` environment variable, or,
     if not set, to the login name of the current OS user.
 
-:cli:synopsis:`-d <dbname>, --database=<dbname>`
-    Specifies the name of the database to connect to. Default to the value
-    of the :gelenv:`DATABASE` environment variable, or, if not set, to
-    the calculated value of :cli:synopsis:`<username>`.
-
 :cli:synopsis:`-b <branch-name>, --branch=<branch-name>`
     Specifies the name of the branch to connect to. Default to the value
     of the :gelenv:`BRANCH` environment variable, or, if not set, to
@@ -234,8 +229,7 @@ Data Operations
   Dump current database branch to a file at *FILENAME*.
 
 :cli:synopsis:`\\restore FILENAME`
-  Restore the database dump at *FILENAME* into the current branch (or currently
-  connected database for pre-v5).
+  Restore the database dump at *FILENAME* into the current |branch|.
 
 Editing
 -------
@@ -273,9 +267,8 @@ without first entering the |Gel| shell. Their counterpart commands are noted
 and linked in their descriptions if you want more detail.
 
 :cli:synopsis:`\\migration create`
-  Create a migration script based on differences between the current branch (or
-  database for pre-v5) and the schema file, just like running
-  :ref:`ref_cli_gel_migration_create`.
+  Create a migration script based on differences between the current |branch|
+   and the schema file, just like running :ref:`ref_cli_gel_migration_create`.
 
 :cli:synopsis:`\\migrate, \\migration apply`
   Apply your migration, just like running the

diff --git a/docs/cli/gel_branch/gel_branch_switch.rst b/docs/cli/gel_branch/gel_branch_switch.rst
@@ -13,12 +13,13 @@ Change the currently active :ref:`branch <ref_datamodel_branches>`
 
 .. note::
 
-    This CLI command requires |Gel| version 5.0 or later. Earlier versions did
-    not feature branches and instead featured databases.
+    This CLI command requires |Gel| (or |EdgeDB| version 5.0 or later.)
+    Earlier versions did not feature branches and instead featured
+    **databases**.
 
     Databases offered no direct analog to switching.
 
-    - To run a single command on a different database, use the ``-d <dbname>``
+    - To run a single command on a different |branch|, use the ``-d <dbname>``
       or ``--database=<dbname>`` options described in
       :ref:`ref_cli_gel_connopts`
     - To change the database for *all* commands, set the :gelenv:`DATABASE`
@@ -42,7 +43,7 @@ connected to. For specifying the connection target see
 :ref:`connection options <ref_cli_gel_connopts>`.
 
 :cli:synopsis:`<name>`
-    The name of the new branch.
+    The name of the new |branch|.
 
 :cli:synopsis:`-c, --create`
     Create the branch if it doesn't exist.

diff --git a/docs/cli/gel_database/gel_database_create.rst b/docs/cli/gel_database/gel_database_create.rst
@@ -5,6 +5,11 @@
 gel database create
 ===================
 
+.. warning::
+
+    This command is deprecated in |Gel|.
+    Use :ref:`ref_cli_gel_branch_create` instead.
+
 Create a new :ref:`database <ref_datamodel_databases>`.
 
 .. cli:synopsis::

diff --git a/docs/cli/gel_database/gel_database_drop.rst b/docs/cli/gel_database/gel_database_drop.rst
@@ -5,6 +5,11 @@
 gel database drop
 =================
 
+.. warning::
+
+    This command is deprecated in |Gel|.
+    Use :ref:`ref_cli_gel_branch_drop` instead.
+
 Drop a :ref:`database <ref_datamodel_databases>`.
 
 .. cli:synopsis::

diff --git a/docs/cli/gel_database/gel_database_wipe.rst b/docs/cli/gel_database/gel_database_wipe.rst
@@ -5,6 +5,11 @@
 gel database wipe
 =================
 
+.. warning::
+
+    This command is deprecated in |Gel|.
+    Use :ref:`ref_cli_gel_branch_wipe` instead.
+
 Destroy the contents of a :ref:`database <ref_datamodel_databases>`
 
 .. cli:synopsis::

diff --git a/docs/cli/gel_describe/index.rst b/docs/cli/gel_describe/index.rst
@@ -21,4 +21,4 @@ introspection tools.
     * - :ref:`ref_cli_gel_describe_object`
       - Describe a named schema object
     * - :ref:`ref_cli_gel_describe_schema`
-      - Describe schema of the current database branch (or database pre-v5)
+      - Describe schema of the current database |branch|
diff --git a/docs/cli/gel_dump.rst b/docs/cli/gel_dump.rst
@@ -5,7 +5,7 @@
 gel dump
 ========
 
-Backup a |Gel| branch (or database pre-v5) to a file.
+Backup a |Gel| |branch| to a file.
 
 .. cli:synopsis::
 
@@ -15,16 +15,15 @@ Backup a |Gel| branch (or database pre-v5) to a file.
 Options
 =======
 
-The ``dump`` command creates a backup of the currently active database branch
-or, in pre-v5 instances, the currently connected database.
+The ``dump`` command creates a backup of the currently active database |branch|.
 For specifying the connection target see :ref:`connection options
 <ref_cli_gel_connopts>`.
 
 :cli:synopsis:`<path>`
     The name of the file to backup the database branch into.
 
 :cli:synopsis:`--all`
-    Dump all branches (databases pre-v5) and the server configuration using the
+    Dump all |branches| and the server configuration using the
     directory specified by the :cli:synopsis:`<path>`.
 
 :cli:synopsis:`--format=<format>`

diff --git a/docs/cli/gel_instance/gel_instance_create.rst b/docs/cli/gel_instance/gel_instance_create.rst
@@ -57,15 +57,16 @@ Options
     The new |Gel| instance name. Asked interactively if not specified.
 
 :cli:synopsis:`<branch-or-database-name>`
-    The default branch (or database pre-v5) name on the new instance. Defaults
-    to |main| or, when creating a pre-v5 instance, ``gel``.
+    The default |branch| name on the new instance. Defaults
+    to |main| or, when creating a pre-v5 instance, ``edgedb``.
 
 :cli:synopsis:`--nightly`
     Use the nightly server for this instance.
 
 :cli:synopsis:`--default-user=<default-user>`
     Specifies the default user name (created during initialization,
-    and saved in credentials file). Defaults to: ``gel``.
+    and saved in credentials file). Defaults to: ``admin``,
+    or, when creating a pre-v6 instance, ``edgedb``.
 
 :cli:synopsis:`--port=<port>`
     Specifies which port should the instance be configured on. By

diff --git a/docs/cli/gel_list.rst b/docs/cli/gel_list.rst
@@ -31,9 +31,6 @@ Types
 :cli:synopsis:`gel list branches`
     Display list of branches.
 
-:cli:synopsis:`gel list databases`
-    Display list of databases in the server instance.
-
 :cli:synopsis:`gel list indexes`
     Display list of indexes defined in the schema.
 
@@ -52,7 +49,7 @@ Types
 Options
 =======
 
-The ``list`` command runs in the database it is connected to. For
+The ``list`` command runs in the |branch| it is connected to. For
 specifying the connection target see :ref:`connection options
 <ref_cli_gel_connopts>`.
 

diff --git a/docs/cli/gel_migration/gel_migration_create.rst b/docs/cli/gel_migration/gel_migration_create.rst
@@ -13,8 +13,8 @@ migration script. This is done by invoking the following command:
     gel migration create [<options>]
 
 This will start an interactive tool that will provide the user with
-suggestions based on the differences between the current branch (or database
-for pre-v5) and the schema file. The prompts will look something like this:
+suggestions based on the differences between the current |branch|
+and the schema file. The prompts will look something like this:
 
 .. code-block::
 

diff --git a/docs/cli/gel_migration/index.rst b/docs/cli/gel_migration/index.rst
@@ -40,7 +40,7 @@ single SDL document.
     :class: funcoptable
 
     * - :ref:`ref_cli_gel_migration_apply`
-      - Bring current branch (or database pre-v5) to the latest or a specified revision
+      - Bring current |branch| to the latest or a specified revision
     * - :ref:`ref_cli_gel_migration_create`
       - Create a migration script
     * - :ref:`ref_cli_gel_migration_edit`

diff --git a/docs/cli/gel_restore.rst b/docs/cli/gel_restore.rst
@@ -5,7 +5,7 @@
 gel restore
 ===========
 
-Restore a |Gel| branch from a backup file.
+Restore a |Gel| |branch| from a backup file.
 
 .. cli:synopsis::
 
@@ -15,20 +15,20 @@ Restore a |Gel| branch from a backup file.
 Description
 ===========
 
-:gelcmd:`restore` is a terminal command used to restore an Gel database
-branch (or database pre-v5) from a backup file. The backup is restored to the
-currently active branch (or to the currently connected database pre-v5).
+:gelcmd:`restore` is a terminal command used to restore an Gel |branch|
+|branch| from a backup file. The backup is restored to the
+currently active branch.
 
 .. note::
 
-    The backup cannot be restored to a branch (or database pre-v5) with any
+    The backup cannot be restored to a |branch| with any
     existing schema. As a result, you should restore to one of these targets:
 
-    - a new empty branch which can be created using
+    - a new empty |branch| which can be created using
       :ref:`ref_cli_gel_branch_create` with the ``--empty`` option
-    - a new empty database if your instance is running |EdgeDB| versions
+    - a new empty |branch| if your instance is running |EdgeDB| versions
       prior to 5
-    - an existing branch or database that has been wiped with the appropriate
+    - an existing |branch| that has been wiped with the appropriate
       ``wipe`` command (either :ref:`ref_cli_gel_branch_wipe` or
       :ref:`ref_cli_gel_database_wipe`; note that this will destroy all data
       and schema currently in that branch/database)
@@ -37,15 +37,15 @@ currently active branch (or to the currently connected database pre-v5).
 Options
 =======
 
-The ``restore`` command restores the backup file into the active branch or, in
-pre-v5 instance, the currently connected database. For specifying the
-connection target see :ref:`connection options <ref_cli_gel_connopts>`.
+The ``restore`` command restores the backup file into the active |branch|.
+For specifying the connection target see :ref:`connection options
+<ref_cli_gel_connopts>`.
 
 :cli:synopsis:`<path>`
-    The name of the backup file to restore the database branch from.
+    The name of the backup file to restore the |branch| from.
 
 :cli:synopsis:`--all`
-    Restore all branches (or databases pre-v5) and the server configuration
+    Restore all |branches| and the server configuration
     using the directory specified by the :cli:synopsis:`<path>`.
 
 :cli:synopsis:`-v, --verbose`

diff --git a/docs/cli/gel_ui.rst b/docs/cli/gel_ui.rst
@@ -35,7 +35,7 @@ table.
 Options
 =======
 
-The ``ui`` command runs on the database it is connected to. For specifying the
+The ``ui`` command runs on the |branch| it is connected to. For specifying the
 connection target see :ref:`connection options <ref_cli_gel_connopts>`.
 
 :cli:synopsis:`--print-url`

diff --git a/docs/cli/gel_watch.rst b/docs/cli/gel_watch.rst
@@ -6,8 +6,8 @@ gel watch
 =========
 
 Start a long-running process that watches for changes in schema files in your
-project's ``dbschema`` directory and applies those changes to your database in
-real time. Starting it is as simple as running this command:
+project's ``dbschema`` directory and applies those changes to your current
+|branch| in real time. Starting it is as simple as running this command:
 
 .. cli:synopsis::
 

diff --git a/docs/cli/index.rst b/docs/cli/index.rst
@@ -138,22 +138,22 @@ The ``cli.toml`` has the following structure. All fields are optional:
     gel_connopts
     network
     gel
-    gel_analyze
+    gel_project/index
+    gel_ui
+    gel_watch
+    gel_migrate
+    gel_migration/index
+    gel_cloud/index
     gel_branch/index
+    gel_dump
+    gel_restore
     gel_configure
+    gel_query
+    gel_analyze
+    gel_list
+    gel_info
     gel_cli_upgrade
-    gel_cloud/index
-    gel_database/index
+    gel_server/index
     gel_describe/index
-    gel_dump
-    gel_info
     gel_instance/index
-    gel_list
-    gel_migrate
-    gel_migration/index
-    gel_project/index
-    gel_query
-    gel_restore
-    gel_server/index
-    gel_ui
-    gel_watch
+    gel_database/index
diff --git a/docs/datamodel/index.rst b/docs/datamodel/index.rst
@@ -126,7 +126,7 @@ your VCS. Each branch has its own schema and data.
 Module
 ^^^^^^
 
-Each branch (or database pre-v5) has a schema consisting of several
+Each |branch| has a schema consisting of several
 **modules**, each with a unique name. Modules can be used to organize large
 schemas into logical units. In practice, though, most users put their entire
 schema inside a single module called ``default``.

diff --git a/docs/stdlib/sys.rst b/docs/stdlib/sys.rst
@@ -95,6 +95,11 @@ System
 
     Return the name of the current database as a string.
 
+    .. note::
+
+        This function is deprecated in |Gel|.
+        Use :eql:func:`sys::get_current_branch` instead.
+
     .. code-block:: edgeql-repl
 
         db> select sys::get_current_database();