Document branches (#7080)

* Document branches

* Add -b connection option

* Change to headings

so that we can easily show/hide changes per version

* Clarify

* Fix issues Quin called out

Co-authored-by: Quin Lynch <[email protected]>

* Correct CLI version req for branch commands

---------

Co-authored-by: Quin Lynch <[email protected]>

docs/cli/edgedb_branch/edgedb_branch_create.rst

@@ -0,0 +1,48 @@
+.. _ref_cli_edgedb_branch_create:
+
+
+====================
+edgedb branch create
+====================
+
+.. note::
+
+    This CLI 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 :ref:`ref_cli_edgedb_database` command suite to manage databases,
+    which branches replaced in EdgeDB 5.0.
+
+Create a new :ref:`branch <ref_datamodel_branches>`.
+
+.. cli:synopsis::
+
+    edgedb branch create [<options>] <name>
+
+
+Description
+===========
+
+``edgedb branch create`` creates a new branch with the same schema as the
+current branch specified in ``$CONFIG/credentials``. Without any options, it is
+equivalent to :eql:stmt:`create schema branch`.
+
+
+Options
+=======
+
+The ``branch create`` command runs in the EdgeDB instance it is
+connected to. For specifying the connection target see
+:ref:`connection options <ref_cli_edgedb_connopts>`.
+
+:cli:synopsis:`<name>`
+    The name of the new branch.
+
+:cli:synopsis:`--from <oldbranch>`
+    The optional base branch to create the new branch from. Defaults to the
+    current branch specified in ``$CONFIG/credentials``.
+
+:cli:synopsis:`-e, --empty`
+    Create a branch with no schema or data.
+
+:cli:synopsis:`--copy-data`
+    Copy data from the base branch to the new branch.

docs/cli/edgedb_branch/edgedb_branch_drop.rst

@@ -0,0 +1,36 @@
+.. _ref_cli_edgedb_branch_drop:
+
+
+==================
+edgedb branch drop
+==================
+
+.. note::
+
+    This CLI 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 :ref:`ref_cli_edgedb_database` command suite to manage databases,
+    which branches replaced in EdgeDB 5.0.
+
+Remove an existing :ref:`branch <ref_datamodel_branches>`.
+
+.. cli:synopsis::
+
+    edgedb branch drop [<options>] <name>
+
+
+Options
+=======
+
+The ``branch drop`` command runs in the EdgeDB instance it is
+connected to. For specifying the connection target see
+:ref:`connection options <ref_cli_edgedb_connopts>`.
+
+:cli:synopsis:`<name>`
+    The name of the branch to drop.
+
+:cli:synopsis:`--non-interactive`
+    Drop the branch without asking for confirmation.
+
+:cli:synopsis:`--force`
+    Close any existing connections to the branch before dropping it.

docs/cli/edgedb_branch/edgedb_branch_list.rst

@@ -0,0 +1,19 @@
+.. _ref_cli_edgedb_branch_list:
+
+
+==================
+edgedb branch list
+==================
+
+.. note::
+
+    This CLI 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 :ref:`ref_cli_edgedb_database` command suite to manage databases,
+    which branches replaced in EdgeDB 5.0.
+
+List all :ref:`branches <ref_datamodel_branches>`
+
+.. cli:synopsis::
+
+    edgedb branch list

docs/cli/edgedb_branch/edgedb_branch_rebase.rst

@@ -0,0 +1,38 @@
+.. _ref_cli_edgedb_branch_rebase:
+
+
+====================
+edgedb branch rebase
+====================
+
+.. note::
+
+    This CLI 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 :ref:`ref_cli_edgedb_database` command suite to manage databases,
+    which branches replaced in EdgeDB 5.0.
+
+Create a :ref:`branch <ref_datamodel_branches>` based on the target branch but
+including new migrations on the current branch.
+
+.. cli:synopsis::
+
+    edgedb branch rebase [<options>] <name>
+
+
+Description
+===========
+
+Creates a new branch that is based on the target branch, but also contains any new migrations on the
+current branch.
+
+
+Options
+=======
+
+The ``branch rebase`` command runs in the EdgeDB instance it is
+connected to. For specifying the connection target see
+:ref:`connection options <ref_cli_edgedb_connopts>`.
+
+:cli:synopsis:`<name>`
+    The name of the target branch.

docs/cli/edgedb_branch/edgedb_branch_rename.rst

@@ -0,0 +1,36 @@
+.. _ref_cli_edgedb_branch_rename:
+
+
+====================
+edgedb branch rename
+====================
+
+.. note::
+
+    This CLI 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 :ref:`ref_cli_edgedb_database` command suite to manage databases,
+    which branches replaced in EdgeDB 5.0.
+
+Rename a :ref:`branch <ref_datamodel_branches>`
+
+.. cli:synopsis::
+
+    edgedb branch rename [<options>] <old-name> <new-name>
+
+
+Options
+=======
+
+The ``branch rename`` command runs in the EdgeDB instance it is
+connected to. For specifying the connection target see
+:ref:`connection options <ref_cli_edgedb_connopts>`.
+
+:cli:synopsis:`<old-name>`
+    The current name of the branch to rename.
+
+:cli:synopsis:`<new-name>`
+    The new name of the branch.
+
+:cli:synopsis:`--force`
+    Close any existing connections to the branch before renaming it.

docs/cli/edgedb_branch/edgedb_branch_switch.rst

@@ -0,0 +1,43 @@
+.. _ref_cli_edgedb_branch_switch:
+
+
+====================
+edgedb branch switch
+====================
+
+.. note::
+
+    This CLI 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 :ref:`ref_cli_edgedb_database` command suite to manage databases,
+    which branches replaced in EdgeDB 5.0.
+
+Change the currently active :ref:`branch <ref_datamodel_branches>`
+
+.. cli:synopsis::
+
+    edgedb branch switch [<options>] <name>
+
+
+Options
+=======
+
+The ``branch switch`` command runs in the EdgeDB instance it is
+connected to. For specifying the connection target see
+:ref:`connection options <ref_cli_edgedb_connopts>`.
+
+:cli:synopsis:`<name>`
+    The name of the new branch.
+
+:cli:synopsis:`-c, --create`
+    Create the branch if it doesn't exist.
+
+:cli:synopsis:`-e, --empty`
+    If creating a new branch: create the branch with no schema or data.
+
+:cli:synopsis:`--from <FROM>`
+    If creating a new branch: the optional base branch to create the new branch
+    from.
+
+:cli:synopsis:`--copy-data`
+    If creating a new branch: copy data from the base branch to the new branch.

docs/cli/edgedb_branch/edgedb_branch_wipe.rst

@@ -0,0 +1,43 @@
+.. _ref_cli_edgedb_branch_wipe:
+
+
+==================
+edgedb branch wipe
+==================
+
+.. note::
+
+    This CLI 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 :ref:`ref_cli_edgedb_database` command suite to manage databases,
+    which branches replaced in EdgeDB 5.0.
+
+Destroy the contents of a :ref:`branch <ref_datamodel_branches>`
+
+.. cli:synopsis::
+
+    edgedb branch wipe [<options>] <name>
+
+
+Description
+===========
+
+The contents of the branch will be destroyed and the schema reset to its
+state before any migrations, but the branch itself will be preserved.
+
+``edgedb branch wipe`` is a terminal command equivalent to
+:eql:stmt:`reset schema to initial`.
+
+
+Options
+=======
+
+The ``branch wipe`` command runs in the EdgeDB instance it is
+connected to. For specifying the connection target see
+:ref:`connection options <ref_cli_edgedb_connopts>`.
+
+:cli:synopsis:`<name>`
+    The name of the branch to wipe.
+
+:cli:synopsis:`--non-interactive`
+    Destroy the data without asking for confirmation.

docs/cli/edgedb_branch/index.rst

@@ -0,0 +1,38 @@
+.. _ref_cli_edgedb_branch:
+
+
+=============
+edgedb branch
+=============
+
+.. note::
+
+    These CLI 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 :ref:`ref_cli_edgedb_database` command suite to manage
+    databases, which branches replaced in EdgeDB 5.0.
+
+The ``edgedb branch`` group of commands contains various branch management
+tools.
+
+.. toctree::
+    :maxdepth: 3
+    :hidden:
+
+    edgedb_branch_create
+    edgedb_branch_drop
+    edgedb_branch_list
+    edgedb_branch_rebase
+    edgedb_branch_rename
+    edgedb_branch_switch
+    edgedb_branch_wipe
+
+.. list-table::
+    :class: funcoptable
+
+    * - :ref:`ref_cli_edgedb_branch_create`
+      - Create a new branch
+    * - :ref:`ref_cli_edgedb_cloud_logout`
+      - Forget the stored access token
+    * - :ref:`ref_cli_edgedb_cloud_secretkey`
+      - Manage your secret keys

docs/cli/edgedb_connopts.rst

@@ -71,6 +71,19 @@ Connection flags
     default to the name provided when the link was created. This also includes
     EdgeDB Cloud instance links created via :ref:`ref_cli_edgedb_project_init`.
 
+    .. note::
+
+        With EdgeDB 5, databases were refactored as branches. If you're using
+        EdgeDB 5+, use the option below instead of this one.
+
+:cli:synopsis:`-b <branch_name>, --branch=<branch_name>`
+    Specifies the name of the branch to connect to. Defaults to the value of
+    the ``EDGEDB_BRANCH`` environment variable. If that variable isn't set,
+    local instances will default to the most recently switched branch or the
+    ``main`` branch, while remote instances will default to the name provided
+    when the link was created. This also includes EdgeDB Cloud instance links
+    created via :ref:`ref_cli_edgedb_project_init`.
+
 :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

docs/cli/index.rst

@@ -139,6 +139,7 @@ The ``cli.toml`` has the following structure. All fields are optional:
     network
     edgedb
     edgedb_analyze
+    edgedb_branch/index
     edgedb_configure
     edgedb_cli_upgrade
     edgedb_cloud/index

docs/datamodel/index.rst

@@ -113,16 +113,31 @@ Terminology
 
 .. _ref_datamodel_instances:
 
-.. rubric:: Instance
+Instance
+^^^^^^^^
 
-An EdgeDB **instance** is a collection of databases that store their data in
-a shared directory, listen for queries on a particular port, and are managed
-by a running EdgeDB process. Instances can be created, started, stopped, and
-destroyed locally with the :ref:`EdgeDB CLI <ref_cli_overview>`.
+An EdgeDB **instance** is a running EdgeDB process. Instances can be created,
+started, stopped, and destroyed locally with the :ref:`EdgeDB CLI
+<ref_cli_overview>`.
+
+.. _ref_datamodel_branches:
+
+Branches
+^^^^^^^^
+
+.. versionadded:: 5.0
+
+Instances can be branched when working on new features, similar to branches in
+your VCS. Each branch has its own schema and data.
 
 .. _ref_datamodel_databases:
 
-.. rubric:: Database
+Database
+^^^^^^^^
+
+.. versionadded:: 5.0
+
+    In EdgeDB 5, databases were replaced by branches.
 
 Each instance can contain several **databases**, each with a unique name. At
 the time of creation, all instances contain a single default database called
@@ -131,12 +146,13 @@ against it unless otherwise specified.
 
 .. _ref_datamodel_modules:
 
-.. rubric:: Module
+Module
+^^^^^^
 
-Each database 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``.
+Each branch (or database pre-v5) 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``.
 
 .. code-block:: sdl