Docs: database -> branches throughout (#7152)

* Document branches * Change to headings so that we can easily show/hide changes per version * WIP: Add branching guides * Update intro and guide content with branching * Add missing `branch merge` doc * Clarify * Add links to merge doc * Add Get started > Branches to TOC * Link to more info about rebasing * Minor copy edits * Link to docs for the correct command * Fix branch commands * Clarify final state of data after rebase * Correct description, add data & strategy notes * Move branch -> db notes & make command-specific Since some branch commands do not have database command analogs, it makes sense to mention this in the notes that tell users branch commands only work on EdgeDB 5+. While I'm here, may as well offer alternatives to those commands where that makes sense. While I'm doing that, may as well make the notes for other commands that do have a database analog point to the specific database alternative. This will make some of these notes much longer, so I moved them below the initial command description. * Add note about VCS compatibility vs. examples * Move cheatsheets so they can be versioned * Update all documentation to include branches * Fix errors and omissions discovered while adding branches * Update CLI output to 5.x * Add TODOs and toggles for blocked v5 docs * Update images for v5 * Fix cheatsheeets URL
geldata · Apr 9, 2024 · 0496533 · 0496533
1 parent 73198ab
commit 0496533
Show file tree

Hide file tree

Showing 77 changed files with 821 additions and 339 deletions.
diff --git a/docs/guides/cheatsheet/admin.rst → docs/cheatsheets/admin.rst b/docs/guides/cheatsheet/admin.rst → docs/cheatsheets/admin.rst
diff --git a/docs/guides/cheatsheet/aliases.rst → docs/cheatsheets/aliases.rst b/docs/guides/cheatsheet/aliases.rst → docs/cheatsheets/aliases.rst
diff --git a/docs/guides/cheatsheet/annotations.rst → docs/cheatsheets/annotations.rst b/docs/guides/cheatsheet/annotations.rst → docs/cheatsheets/annotations.rst
diff --git a/docs/guides/cheatsheet/boolean.rst → docs/cheatsheets/boolean.rst b/docs/guides/cheatsheet/boolean.rst → docs/cheatsheets/boolean.rst
diff --git a/docs/guides/cheatsheet/cli.rst → docs/cheatsheets/cli.rst b/docs/guides/cheatsheet/cli.rst → docs/cheatsheets/cli.rst
@@ -34,11 +34,11 @@ Explicitly create a new EdgeDB instance ``my_instance``:
 ----------
 
 
-Create a database:
+Create a branch:
 
 .. code-block:: bash
 
-    $ edgedb database create special_db
+    $ edgedb branch create feature
     OK: CREATE
 
 
@@ -73,7 +73,7 @@ Configure access that checks password (with a higher priority):
 ----------
 
 
-Connect to the default project database:
+Connect to the default project branch:
 
 .. code-block:: bash
 
@@ -86,11 +86,11 @@ Connect to the default project database:
 ----------
 
 
-Connect to some specific database:
+Connect to some specific branch:
 
 .. code-block:: bash
 
-    $ edgedb -d special_db
+    $ edgedb -b feature
     EdgeDB 1.0-beta.2+ga7130d5c7.cv202104290000 (repl 1.0.0-beta.2)
     Type \help for help, \quit to quit.
     special_db>
diff --git a/docs/guides/cheatsheet/delete.rst → docs/cheatsheets/delete.rst b/docs/guides/cheatsheet/delete.rst → docs/cheatsheets/delete.rst
diff --git a/docs/guides/cheatsheet/functions.rst → docs/cheatsheets/functions.rst b/docs/guides/cheatsheet/functions.rst → docs/cheatsheets/functions.rst
diff --git a/docs/guides/cheatsheet/index.rst → docs/cheatsheets/index.rst b/docs/guides/cheatsheet/index.rst → docs/cheatsheets/index.rst
@@ -64,5 +64,5 @@ CLI/Admin
 * :ref:`CLI Usage <ref_cheatsheet_cli>` -- Getting your database started.
 * :ref:`Interactive Shell <ref_cheatsheet_repl>` -- Shortcuts for
   frequently used commands in the EdgeDB Interactive Shell.
-* :ref:`Administration <ref_cheatsheet_admin>` -- Database and role creation,
+* :ref:`Administration <ref_cheatsheet_admin>` -- Branch and role creation,
   passwords, port configuration, etc.
diff --git a/docs/guides/cheatsheet/insert.rst → docs/cheatsheets/insert.rst b/docs/guides/cheatsheet/insert.rst → docs/cheatsheets/insert.rst
diff --git a/docs/guides/cheatsheet/link_properties.rst → docs/cheatsheets/link_properties.rst b/docs/guides/cheatsheet/link_properties.rst → docs/cheatsheets/link_properties.rst
diff --git a/docs/guides/cheatsheet/objects.rst → docs/cheatsheets/objects.rst b/docs/guides/cheatsheet/objects.rst → docs/cheatsheets/objects.rst
diff --git a/docs/guides/cheatsheet/repl.rst → docs/cheatsheets/repl.rst b/docs/guides/cheatsheet/repl.rst → docs/cheatsheets/repl.rst
diff --git a/docs/guides/cheatsheet/select.rst → docs/cheatsheets/select.rst b/docs/guides/cheatsheet/select.rst → docs/cheatsheets/select.rst
diff --git a/docs/guides/cheatsheet/update.rst → docs/cheatsheets/update.rst b/docs/guides/cheatsheet/update.rst → docs/cheatsheets/update.rst
diff --git a/docs/cli/edgedb.rst b/docs/cli/edgedb.rst
@@ -81,10 +81,23 @@ Options
     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
+    Specifies the name of the database to connect to. Default to the value
     of the ``EDGEDB_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 ``EDGEDB_BRANCH`` environment variable, or, if not set, to
+    the calculated value of :cli:synopsis:`<username>`.
+
+    .. note::
+
+        EdgeDB 5.0 introduced :ref:`branches <ref_datamodel_branches>` to
+        replace databases. This option requires CLI version 4.3.0 or later and
+        EdgeDB version 5.0 or later. If you are running an earlier version of
+        EdgeDB, you will instead use the ``-d <dbname>, --database=<dbname>``
+        option above.
+
 :cli:synopsis:`--password | --no-password`
     If :cli:synopsis:`--password` is specified, force ``edgedb`` to prompt
     for a password before connecting to the database.  This is usually not
@@ -139,7 +152,8 @@ Options
 Backslash Commands
 ==================
 
-.. rubric:: Introspection
+Introspection
+-------------
 
 The introspection commands share a few common options that are available to
 many of the commands:
@@ -157,6 +171,26 @@ many of the commands:
 :cli:synopsis:`\\l, \\list databases`
   List databases.
 
+.. TODO: toggle on once backslash commands are added
+
+  .. note::
+
+      EdgeDB 5.0 introduced :ref:`branches <ref_datamodel_branches>` to replace
+      databases. If you are running 5.0 or later, you will instead use the
+      ``\list branches`` command below.
+
+.. TODO: toggle on once backslash commands are added
+
+    :cli:synopsis:`\\l, \\list branches`
+      List branches.
+
+      .. note::
+
+          EdgeDB 5.0 introduced :ref:`branches <ref_datamodel_branches>` to replace
+          databases. This command requires CLI version 4.3.0 or later and EdgeDB
+          version 5.0 or later. If you are running an earlier version of EdgeDB,
+          you will instead use the ``\list databases`` command above.
+
 :cli:synopsis:`\\ls [-sc] [PATTERN], \\list scalars [-sc] [PATTERN]`
   List scalar types.
 
@@ -178,14 +212,42 @@ many of the commands:
 :cli:synopsis:`\\li [-vsc] [PATTERN], \\list indexes [-vsc] [PATTERN]`
   List indexes.
 
-.. rubric:: Database
+Database
+--------
+
+.. TODO: Once the branch backslash commands are done and documented below, this can toggle on.
 
-:cli:synopsis:`\\database create [NAME]`
+  .. note::
+
+      EdgeDB 5.0 introduced :ref:`branches <ref_datamodel_branches>` to replace
+      databases. If you are running 5.0 or later, you will instead use the
+      commands in the "Branches" section below.
+
+:cli:synopsis:`\\database create NAME`
   Create a new database.
 
-.. rubric:: Query Analysis
+.. TODO: will need to hold these until they are finalized
+
+  Branch
+  ------
+
+    .. note::
+
+        EdgeDB 5.0 introduced :ref:`branches <ref_datamodel_branches>` to replace
+        databases. These commands require CLI version 4.3.0 or later and EdgeDB
+        version 5.0 or later. If you are running an earlier version of EdgeDB,
+        you will instead use the database commands above.
+
+  :cli:synopsis:`\\branch create NAME`
+    Create a new branch.
 
 
+  :cli:synopsis:`\\branch switch NAME`
+    Switch to a different branch.
+
+Query Analysis
+--------------
+
 :cli:synopsis:`\\analyze QUERY`
   .. note::
 
@@ -201,16 +263,18 @@ many of the commands:
 
   Print expanded output of last ``analyze`` operation.
 
-.. rubric:: Data Operations
+Data Operations
+---------------
 
 :cli:synopsis:`\\dump FILENAME`
-  Dump current database to a file at *FILENAME*.
+  Dump current database branch to a file at *FILENAME*.
 
 :cli:synopsis:`\\restore FILENAME`
-  Restore the database dump at *FILENAME* into the currently connected
-  database.
+  Restore the database dump at *FILENAME* into the current branch (or currently
+  connected database for pre-v5).
 
-.. rubric:: Editing
+Editing
+-------
 
 :cli:synopsis:`\\s, \\history`
   Show a history of commands executed in the shell.
@@ -223,27 +287,38 @@ many of the commands:
 
   The output of this will then be used as input into the shell.
 
-.. rubric:: Settings
+Settings
+--------
 
 :cli:synopsis:`\\set [OPTION [VALUE]]`
   If *VALUE* is omitted, the command will show the current value of *OPTION*.
   With *VALUE*, the option named by *OPTION* will be set to the provided value.
   Use ``\set`` with no arguments for a listing of all available options.
 
-.. rubric:: Connection
+Connection
+----------
 
 :cli:synopsis:`\\c, \\connect [DBNAME]`
   Connect to database *DBNAME*.
 
-.. rubric:: Migrations
+.. TODO: toggle on once backslash commands are added
+
+  .. note::
+
+      EdgeDB 5.0 introduced :ref:`branches <ref_datamodel_branches>` to replace
+      databases. If you are running 5.0 or later, you will instead use the
+      ``\branch switch NAME`` command to switch to a different branch.
+
+Migrations
+----------
 
 These migration commands are also accessible directly from the command line
 without first entering the EdgeDB 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 database
-  and the schema file, just like running
+  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_edgedb_migration_create`.
 
 :cli:synopsis:`\\migrate, \\migration apply`
@@ -263,7 +338,8 @@ and linked in their descriptions if you want more detail.
   migration stored in the schema directory, just like
   :ref:`ref_cli_edgedb_migration_status`.
 
-.. rubric:: Help
+Help
+----
 
 :cli:synopsis:`\\?, \\h, \\help`
   Show help on backslash commands.

diff --git a/docs/cli/edgedb_connopts.rst b/docs/cli/edgedb_connopts.rst
@@ -86,7 +86,7 @@ Connection flags
 
 :cli:synopsis:`--password | --no-password`
     If :cli:synopsis:`--password` is specified, force ``edgedb`` to prompt
-    for a password before connecting to the database.  This is usually not
+    for a password before connecting to the database. This is usually not
     necessary, since ``edgedb`` will prompt for a password automatically
     if the server requires it.
 

diff --git a/docs/cli/edgedb_database/edgedb_database_create.rst b/docs/cli/edgedb_database/edgedb_database_create.rst
@@ -11,6 +11,13 @@ Create a new :ref:`database <ref_datamodel_databases>`.
 
     edgedb database create [<options>] <name>
 
+.. note::
+
+    EdgeDB 5.0 introduced :ref:`branches <ref_datamodel_branches>` to
+    replace databases. This command works on instances running versions
+    prior to EdgeDB 5.0. If you are running a newer version of
+    EdgeDB, you will instead use :ref:`ref_cli_edgedb_branch_create`.
+
 
 Description
 ===========

diff --git a/docs/cli/edgedb_database/edgedb_database_drop.rst b/docs/cli/edgedb_database/edgedb_database_drop.rst
@@ -11,6 +11,13 @@ Drop a :ref:`database <ref_datamodel_databases>`.
 
     edgedb database drop [<options>] <name>
 
+.. note::
+
+    EdgeDB 5.0 introduced :ref:`branches <ref_datamodel_branches>` to
+    replace databases. This command works on instances running versions
+    prior to EdgeDB 5.0. If you are running a newer version of
+    EdgeDB, you will instead use :ref:`ref_cli_edgedb_branch_drop`.
+
 
 Description
 ===========

diff --git a/docs/cli/edgedb_database/edgedb_database_wipe.rst b/docs/cli/edgedb_database/edgedb_database_wipe.rst
@@ -11,6 +11,13 @@ Destroy the contents of a :ref:`database <ref_datamodel_databases>`
 
     edgedb database wipe [<options>]
 
+.. note::
+
+    EdgeDB 5.0 introduced :ref:`branches <ref_datamodel_branches>` to
+    replace databases. This command works on instances running versions
+    prior to EdgeDB 5.0. If you are running a newer version of
+    EdgeDB, you will instead use :ref:`ref_cli_edgedb_branch_wipe`.
+
 
 Description
 ===========

diff --git a/docs/cli/edgedb_database/index.rst b/docs/cli/edgedb_database/index.rst
@@ -8,6 +8,14 @@ edgedb database
 The ``edgedb database`` group of commands contains various database
 manipulation tools.
 
+.. note::
+
+    EdgeDB 5.0 introduced :ref:`branches <ref_datamodel_branches>` to
+    replace databases. These commands work on instances running versions
+    prior to EdgeDB 5.0. If you are running a newer version of
+    EdgeDB, you will instead use the :ref:`ref_cli_edgedb_branch` suite of
+    commands.
+
 .. toctree::
     :maxdepth: 3
     :hidden:

diff --git a/docs/cli/edgedb_describe/index.rst b/docs/cli/edgedb_describe/index.rst
@@ -21,4 +21,4 @@ introspection tools.
     * - :ref:`ref_cli_edgedb_describe_object`
       - Describe a named schema object
     * - :ref:`ref_cli_edgedb_describe_schema`
-      - Describe schema of the current database
+      - Describe schema of the current database branch (or database pre-v5)
diff --git a/docs/cli/edgedb_dump.rst b/docs/cli/edgedb_dump.rst
@@ -5,32 +5,26 @@
 edgedb dump
 ===========
 
-Backup an EdgeDB database to a file.
+Backup an EdgeDB branch (or database pre-v5) to a file.
 
 .. cli:synopsis::
 
     edgedb dump [<options>] <path>
 
 
-Description
-===========
-
-``edgedb dump`` is a terminal command used to backup an EdgeDB database
-into a file.
-
-
 Options
 =======
 
-The ``dump`` command backups the database it is connected to. For
-specifying the connection target see :ref:`connection options
+The ``dump`` command creates a backup of the currently active database branch
+or, in pre-v5 instances, the currently connected database.
+For specifying the connection target see :ref:`connection options
 <ref_cli_edgedb_connopts>`.
 
 :cli:synopsis:`<path>`
-    The name of the file to backup the database into.
+    The name of the file to backup the database branch into.
 
 :cli:synopsis:`--all`
-    Dump all databases and the server configuration using the
+    Dump all branches (databases pre-v5) and the server configuration using the
     directory specified by the :cli:synopsis:`<path>`.
 
 :cli:synopsis:`--format=<format>`