From 4880e35cf8f65d814365d600cd846ac87b2ffb5d Mon Sep 17 00:00:00 2001 From: Devon Campbell Date: Wed, 20 Mar 2024 16:02:04 -0400 Subject: [PATCH] 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 <49576606+quinchs@users.noreply.github.com> * Correct CLI version req for branch commands --------- Co-authored-by: Quin Lynch <49576606+quinchs@users.noreply.github.com> --- .../edgedb_branch/edgedb_branch_create.rst | 48 ++++++ docs/cli/edgedb_branch/edgedb_branch_drop.rst | 36 +++++ docs/cli/edgedb_branch/edgedb_branch_list.rst | 19 +++ .../edgedb_branch/edgedb_branch_rebase.rst | 38 +++++ .../edgedb_branch/edgedb_branch_rename.rst | 36 +++++ .../edgedb_branch/edgedb_branch_switch.rst | 43 +++++ docs/cli/edgedb_branch/edgedb_branch_wipe.rst | 43 +++++ docs/cli/edgedb_branch/index.rst | 38 +++++ docs/cli/edgedb_connopts.rst | 13 ++ docs/cli/index.rst | 1 + docs/datamodel/index.rst | 38 +++-- docs/reference/admin/branches.rst | 153 ++++++++++++++++++ docs/reference/admin/databases.rst | 4 + docs/reference/admin/index.rst | 1 + 14 files changed, 500 insertions(+), 11 deletions(-) create mode 100644 docs/cli/edgedb_branch/edgedb_branch_create.rst create mode 100644 docs/cli/edgedb_branch/edgedb_branch_drop.rst create mode 100644 docs/cli/edgedb_branch/edgedb_branch_list.rst create mode 100644 docs/cli/edgedb_branch/edgedb_branch_rebase.rst create mode 100644 docs/cli/edgedb_branch/edgedb_branch_rename.rst create mode 100644 docs/cli/edgedb_branch/edgedb_branch_switch.rst create mode 100644 docs/cli/edgedb_branch/edgedb_branch_wipe.rst create mode 100644 docs/cli/edgedb_branch/index.rst create mode 100644 docs/reference/admin/branches.rst diff --git a/docs/cli/edgedb_branch/edgedb_branch_create.rst b/docs/cli/edgedb_branch/edgedb_branch_create.rst new file mode 100644 index 00000000000..4bfaf295d20 --- /dev/null +++ b/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 `. + +.. cli:synopsis:: + + edgedb branch create [] + + +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 `. + +:cli:synopsis:`` + The name of the new branch. + +:cli:synopsis:`--from ` + 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. diff --git a/docs/cli/edgedb_branch/edgedb_branch_drop.rst b/docs/cli/edgedb_branch/edgedb_branch_drop.rst new file mode 100644 index 00000000000..66f7fbdc2e7 --- /dev/null +++ b/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 `. + +.. cli:synopsis:: + + edgedb branch drop [] + + +Options +======= + +The ``branch drop`` command runs in the EdgeDB instance it is +connected to. For specifying the connection target see +:ref:`connection options `. + +:cli:synopsis:`` + 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. diff --git a/docs/cli/edgedb_branch/edgedb_branch_list.rst b/docs/cli/edgedb_branch/edgedb_branch_list.rst new file mode 100644 index 00000000000..7bb98b863cf --- /dev/null +++ b/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 ` + +.. cli:synopsis:: + + edgedb branch list diff --git a/docs/cli/edgedb_branch/edgedb_branch_rebase.rst b/docs/cli/edgedb_branch/edgedb_branch_rebase.rst new file mode 100644 index 00000000000..8ca5167fedb --- /dev/null +++ b/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 ` based on the target branch but +including new migrations on the current branch. + +.. cli:synopsis:: + + edgedb branch rebase [] + + +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 `. + +:cli:synopsis:`` + The name of the target branch. diff --git a/docs/cli/edgedb_branch/edgedb_branch_rename.rst b/docs/cli/edgedb_branch/edgedb_branch_rename.rst new file mode 100644 index 00000000000..2907bb0903d --- /dev/null +++ b/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 ` + +.. cli:synopsis:: + + edgedb branch rename [] + + +Options +======= + +The ``branch rename`` command runs in the EdgeDB instance it is +connected to. For specifying the connection target see +:ref:`connection options `. + +:cli:synopsis:`` + The current name of the branch to rename. + +:cli:synopsis:`` + The new name of the branch. + +:cli:synopsis:`--force` + Close any existing connections to the branch before renaming it. diff --git a/docs/cli/edgedb_branch/edgedb_branch_switch.rst b/docs/cli/edgedb_branch/edgedb_branch_switch.rst new file mode 100644 index 00000000000..d19ff627ccd --- /dev/null +++ b/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 ` + +.. cli:synopsis:: + + edgedb branch switch [] + + +Options +======= + +The ``branch switch`` command runs in the EdgeDB instance it is +connected to. For specifying the connection target see +:ref:`connection options `. + +:cli:synopsis:`` + 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 ` + 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. diff --git a/docs/cli/edgedb_branch/edgedb_branch_wipe.rst b/docs/cli/edgedb_branch/edgedb_branch_wipe.rst new file mode 100644 index 00000000000..76636bad6a6 --- /dev/null +++ b/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 ` + +.. cli:synopsis:: + + edgedb branch wipe [] + + +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 `. + +:cli:synopsis:`` + The name of the branch to wipe. + +:cli:synopsis:`--non-interactive` + Destroy the data without asking for confirmation. diff --git a/docs/cli/edgedb_branch/index.rst b/docs/cli/edgedb_branch/index.rst new file mode 100644 index 00000000000..2a02b356b44 --- /dev/null +++ b/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 diff --git a/docs/cli/edgedb_connopts.rst b/docs/cli/edgedb_connopts.rst index 39ebbba0b36..073dc1c6476 100644 --- a/docs/cli/edgedb_connopts.rst +++ b/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=` + 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 diff --git a/docs/cli/index.rst b/docs/cli/index.rst index b943b0503ef..e442bbdda9b 100644 --- a/docs/cli/index.rst +++ b/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 diff --git a/docs/datamodel/index.rst b/docs/datamodel/index.rst index 8c536462fba..ea582e88919 100644 --- a/docs/datamodel/index.rst +++ b/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 `. +An EdgeDB **instance** is a running EdgeDB process. Instances can be created, +started, stopped, and destroyed locally with the :ref:`EdgeDB CLI +`. + +.. _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 diff --git a/docs/reference/admin/branches.rst b/docs/reference/admin/branches.rst new file mode 100644 index 00000000000..aef50e06fde --- /dev/null +++ b/docs/reference/admin/branches.rst @@ -0,0 +1,153 @@ +.. versionadded:: 5.0 + +.. _ref_admin_branches: + +====== +Branch +====== + +:edb-alt-title: Branches + + +This section describes the administrative commands pertaining to +:ref:`branchs `. + + +Create empty branch +=================== + +:eql-statement: + +Create a new branch without schema or data. + +.. eql:synopsis:: + + create empty branch ; + +Description +----------- + +The command ``create empty branch`` creates a new EdgeDB branch without schema +or data, aside from standard schemas. + +Examples +-------- + +Create a new empty branch: + +.. code-block:: edgeql + + create empty branch newbranch; + + +Create schema branch +==================== + +:eql-statement: + +Create a new branch copying the schema of an existing branch. + +.. eql:synopsis:: + + create schema branch from ; + +Description +----------- + +The command ``create schema branch`` creates a new EdgeDB branch with schema +copied from an already existing branch. + +Examples +-------- + +Create a new schema branch: + +.. code-block:: edgeql + + create schema branch feature from main; + + +Create data branch +================== + +:eql-statement: + +Create a new branch copying the schema and data of an existing branch. + +.. eql:synopsis:: + + create data branch from ; + +Description +----------- + +The command ``create data branch`` creates a new EdgeDB branch with schema and +data copied from an already existing branch. + +Examples +-------- + +Create a new data branch: + +.. code-block:: edgeql + + create data branch feature from main; + + +Drop branch +=========== + +:eql-statement: + +Remove a branch. + +.. eql:synopsis:: + + drop branch ; + +Description +----------- + +The command ``drop branch`` removes an existing branch. It cannot be executed +while there are existing connections to the target branch. + +.. warning:: + + Executing ``drop branch`` removes data permanently and cannot be undone. + +Examples +-------- + +Remove a branch: + +.. code-block:: edgeql + + drop branch appdb; + + +Alter branch +============ + +:eql-statement: + +Rename a branch. + +.. eql:synopsis:: + + alter branch rename to ; + +Description +----------- + +The command ``alter branch … rename`` changes the name of an existing branch. +It cannot be executed while there are existing connections to the target +branch. + +Examples +-------- + +Rename a branch: + +.. code-block:: edgeql + + alter branch featuer rename to feature; diff --git a/docs/reference/admin/databases.rst b/docs/reference/admin/databases.rst index 0f797c1822c..d825d40366e 100644 --- a/docs/reference/admin/databases.rst +++ b/docs/reference/admin/databases.rst @@ -6,6 +6,10 @@ Database :edb-alt-title: Databases +.. versionadded:: 5.0 + + In EdgeDB 5.0, databases were replaced by :ref:`branches + `. This section describes the administrative commands pertaining to :ref:`databases `. diff --git a/docs/reference/admin/index.rst b/docs/reference/admin/index.rst index 9ba7dae60f0..9a21c1a8048 100644 --- a/docs/reference/admin/index.rst +++ b/docs/reference/admin/index.rst @@ -23,6 +23,7 @@ Administrative commands for managing EdgeDB: :maxdepth: 3 :hidden: + branches configure databases roles