Document branches

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.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.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,27 @@
+.. _ref_cli_edgedb_branch_list:
+
+
+==================
+edgedb branch list
+==================
+
+.. note::
+
+    This CLI command requires CLI version 4.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 [<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>`.

docs/cli/edgedb_branch/edgedb_branch_rebase.rst

@@ -0,0 +1,51 @@
+.. _ref_cli_edgedb_branch_rebase:
+
+
+====================
+edgedb branch rebase
+====================
+
+.. note::
+
+    This CLI command requires CLI version 4.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.
+
+: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_rename.rst

@@ -0,0 +1,36 @@
+.. _ref_cli_edgedb_branch_rename:
+
+
+====================
+edgedb branch rename
+====================
+
+.. note::
+
+    This CLI command requires CLI version 4.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.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,45 @@
+.. _ref_cli_edgedb_branch_wipe:
+
+
+==================
+edgedb branch wipe
+==================
+
+.. note::
+
+    This CLI command requires CLI version 4.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 branch wiped will be one of these values: the value passed for the
+``--branch``/``-b`` option, the value of ``EDGEDB_BRANCH``, or ``edgedb``.
+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.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/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

@@ -115,15 +115,27 @@ Terminology
 
 .. rubric:: 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:
+
+.. rubric:: Branches
+
+.. versionadded:: 5.0
+
+Each instance 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
 
+.. 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
 ``edgedb``. All incoming queries are executed
@@ -133,10 +145,10 @@ against it unless otherwise specified.
 
 .. rubric:: 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