From 3b0ae3a367efedf5b9cc0588f81bbca4dd5c8728 Mon Sep 17 00:00:00 2001 From: Devon Campbell Date: Mon, 18 Mar 2024 09:25:33 -0400 Subject: [PATCH] Document branches --- .../edgedb_branch/edgedb_branch_create.rst | 48 ++++++ docs/cli/edgedb_branch/edgedb_branch_drop.rst | 36 +++++ docs/cli/edgedb_branch/edgedb_branch_list.rst | 27 ++++ .../edgedb_branch/edgedb_branch_rebase.rst | 51 ++++++ .../edgedb_branch/edgedb_branch_rename.rst | 36 +++++ .../edgedb_branch/edgedb_branch_switch.rst | 43 +++++ docs/cli/edgedb_branch/edgedb_branch_wipe.rst | 45 ++++++ docs/cli/edgedb_branch/index.rst | 38 +++++ docs/cli/index.rst | 1 + docs/datamodel/index.rst | 28 +++- docs/reference/admin/branches.rst | 153 ++++++++++++++++++ docs/reference/admin/databases.rst | 4 + docs/reference/admin/index.rst | 1 + 13 files changed, 503 insertions(+), 8 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..e137b4dedea --- /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.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..6c74032a196 --- /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.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..029e1e3c5c3 --- /dev/null +++ b/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 ` + +.. cli:synopsis:: + + edgedb branch list [] + + +Options +======= + +The ``branch rename`` command runs in the EdgeDB instance it is +connected to. For specifying the connection target see +:ref:`connection options `. 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..f696571566f --- /dev/null +++ b/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 ` 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. + +: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_rename.rst b/docs/cli/edgedb_branch/edgedb_branch_rename.rst new file mode 100644 index 00000000000..4f10416fa47 --- /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.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..a5f111a47ff --- /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.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..ad65e954bcb --- /dev/null +++ b/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 ` + +.. cli:synopsis:: + + edgedb branch wipe [] + + +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 `. + +: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..2ca281903a4 --- /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.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/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..77ba9d9d902 100644 --- a/docs/datamodel/index.rst +++ b/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 `. +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: + +.. 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 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