From 05d05e00bcf381f5d8be477a4e489c32bc04a70c Mon Sep 17 00:00:00 2001 From: Yury Selivanov Date: Sat, 15 Feb 2025 13:44:30 -0800 Subject: [PATCH] Some branches<>databases footwork --- docs/ai/index.rst | 2 +- docs/ai/reference.rst | 2 +- docs/cheatsheets/repl.rst | 16 +++++------ docs/cli/gel.rst | 13 ++------- docs/cli/gel_branch/gel_branch_switch.rst | 9 +++--- docs/cli/gel_database/gel_database_create.rst | 5 ++++ docs/cli/gel_database/gel_database_drop.rst | 5 ++++ docs/cli/gel_database/gel_database_wipe.rst | 5 ++++ docs/cli/gel_describe/index.rst | 2 +- docs/cli/gel_dump.rst | 7 ++--- docs/cli/gel_instance/gel_instance_create.rst | 7 +++-- docs/cli/gel_list.rst | 5 +--- .../gel_migration/gel_migration_create.rst | 4 +-- docs/cli/gel_migration/index.rst | 2 +- docs/cli/gel_restore.rst | 26 ++++++++--------- docs/cli/gel_ui.rst | 2 +- docs/cli/gel_watch.rst | 4 +-- docs/cli/index.rst | 28 +++++++++---------- docs/datamodel/index.rst | 2 +- docs/stdlib/sys.rst | 5 ++++ edb/tools/docs/edb.py | 7 +++-- 21 files changed, 86 insertions(+), 72 deletions(-) diff --git a/docs/ai/index.rst b/docs/ai/index.rst index 2e38ad47d8a..88134092fdf 100644 --- a/docs/ai/index.rst +++ b/docs/ai/index.rst @@ -85,7 +85,7 @@ You may alternatively configure a provider via EdgeQL: .. code-block:: edgeql - configure current database + configure current branch insert ext::ai::OpenAIProviderConfig { secret := 'sk-....', }; diff --git a/docs/ai/reference.rst b/docs/ai/reference.rst index 3ab6e09a8ed..85557ff33fb 100644 --- a/docs/ai/reference.rst +++ b/docs/ai/reference.rst @@ -63,7 +63,7 @@ via EdgeQL: .. code-block:: edgeql - configure current database + configure current branch insert ext::ai::OpenAIProviderConfig { secret := 'sk-....', }; diff --git a/docs/cheatsheets/repl.rst b/docs/cheatsheets/repl.rst index ead562a9eb7..ae7d739a96f 100644 --- a/docs/cheatsheets/repl.rst +++ b/docs/cheatsheets/repl.rst @@ -67,10 +67,10 @@ Commands * - ``\ds, \describe schema`` - Describe the entire schema. - * - ``\list databases`` + * - ``\list branches`` ``alias: \l`` - - List databases. + - List |branches|. * - ``\list scalars [-sI] [pattern]`` ``alias: \ls`` @@ -101,10 +101,10 @@ Commands - List indexes. * - ``\dump `` - - Dump the current database to file. + - Dump the current |branch| to file. * - ``\restore `` - - Restore the database from a dump file. + - Restore the |branch| from a dump file. * - ``\s, \history`` - Show query history @@ -120,18 +120,18 @@ Commands Type ``\set`` to see all available settings. * - ``\c, \connect []`` - - Connect to a particular database. + - Connect to a particular |branch|. Sample usage ^^^^^^^^^^^^ -List databases: +List |branches|: .. code-block:: edgeql-repl db> \ls - List of databases: + List of branches: db tutorial @@ -140,7 +140,7 @@ List databases: ---------- -Connect to a database: +Connect to a |branch|: .. code-block:: edgeql-repl diff --git a/docs/cli/gel.rst b/docs/cli/gel.rst index 0536a1c918c..f8c57b12654 100644 --- a/docs/cli/gel.rst +++ b/docs/cli/gel.rst @@ -80,11 +80,6 @@ Options Defaults to the value of the :gelenv:`USER` environment variable, or, if not set, to the login name of the current OS user. -:cli:synopsis:`-d , --database=` - Specifies the name of the database to connect to. Default to the value - of the :gelenv:`DATABASE` environment variable, or, if not set, to - the calculated value of :cli:synopsis:``. - :cli:synopsis:`-b , --branch=` Specifies the name of the branch to connect to. Default to the value of the :gelenv:`BRANCH` environment variable, or, if not set, to @@ -234,8 +229,7 @@ Data Operations Dump current database branch to a file at *FILENAME*. :cli:synopsis:`\\restore FILENAME` - Restore the database dump at *FILENAME* into the current branch (or currently - connected database for pre-v5). + Restore the database dump at *FILENAME* into the current |branch|. Editing ------- @@ -273,9 +267,8 @@ without first entering the |Gel| 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 branch (or - database for pre-v5) and the schema file, just like running - :ref:`ref_cli_gel_migration_create`. + Create a migration script based on differences between the current |branch| + and the schema file, just like running :ref:`ref_cli_gel_migration_create`. :cli:synopsis:`\\migrate, \\migration apply` Apply your migration, just like running the diff --git a/docs/cli/gel_branch/gel_branch_switch.rst b/docs/cli/gel_branch/gel_branch_switch.rst index a5f63a0a3a4..0da095349f2 100644 --- a/docs/cli/gel_branch/gel_branch_switch.rst +++ b/docs/cli/gel_branch/gel_branch_switch.rst @@ -13,12 +13,13 @@ Change the currently active :ref:`branch ` .. note:: - This CLI command requires |Gel| version 5.0 or later. Earlier versions did - not feature branches and instead featured databases. + This CLI command requires |Gel| (or |EdgeDB| version 5.0 or later.) + Earlier versions did not feature branches and instead featured + **databases**. Databases offered no direct analog to switching. - - To run a single command on a different database, use the ``-d `` + - To run a single command on a different |branch|, use the ``-d `` or ``--database=`` options described in :ref:`ref_cli_gel_connopts` - To change the database for *all* commands, set the :gelenv:`DATABASE` @@ -42,7 +43,7 @@ connected to. For specifying the connection target see :ref:`connection options `. :cli:synopsis:`` - The name of the new branch. + The name of the new |branch|. :cli:synopsis:`-c, --create` Create the branch if it doesn't exist. diff --git a/docs/cli/gel_database/gel_database_create.rst b/docs/cli/gel_database/gel_database_create.rst index 32ae7a58087..c796f39490b 100644 --- a/docs/cli/gel_database/gel_database_create.rst +++ b/docs/cli/gel_database/gel_database_create.rst @@ -5,6 +5,11 @@ gel database create =================== +.. warning:: + + This command is deprecated in |Gel|. + Use :ref:`ref_cli_gel_branch_create` instead. + Create a new :ref:`database `. .. cli:synopsis:: diff --git a/docs/cli/gel_database/gel_database_drop.rst b/docs/cli/gel_database/gel_database_drop.rst index b6b32edba05..edde6e8b0f2 100644 --- a/docs/cli/gel_database/gel_database_drop.rst +++ b/docs/cli/gel_database/gel_database_drop.rst @@ -5,6 +5,11 @@ gel database drop ================= +.. warning:: + + This command is deprecated in |Gel|. + Use :ref:`ref_cli_gel_branch_drop` instead. + Drop a :ref:`database `. .. cli:synopsis:: diff --git a/docs/cli/gel_database/gel_database_wipe.rst b/docs/cli/gel_database/gel_database_wipe.rst index 51dca94e164..d532bc4d654 100644 --- a/docs/cli/gel_database/gel_database_wipe.rst +++ b/docs/cli/gel_database/gel_database_wipe.rst @@ -5,6 +5,11 @@ gel database wipe ================= +.. warning:: + + This command is deprecated in |Gel|. + Use :ref:`ref_cli_gel_branch_wipe` instead. + Destroy the contents of a :ref:`database ` .. cli:synopsis:: diff --git a/docs/cli/gel_describe/index.rst b/docs/cli/gel_describe/index.rst index 940b37fb803..1ad9f459ca2 100644 --- a/docs/cli/gel_describe/index.rst +++ b/docs/cli/gel_describe/index.rst @@ -21,4 +21,4 @@ introspection tools. * - :ref:`ref_cli_gel_describe_object` - Describe a named schema object * - :ref:`ref_cli_gel_describe_schema` - - Describe schema of the current database branch (or database pre-v5) + - Describe schema of the current database |branch| diff --git a/docs/cli/gel_dump.rst b/docs/cli/gel_dump.rst index 17a8d14001a..5199e2fdcfc 100644 --- a/docs/cli/gel_dump.rst +++ b/docs/cli/gel_dump.rst @@ -5,7 +5,7 @@ gel dump ======== -Backup a |Gel| branch (or database pre-v5) to a file. +Backup a |Gel| |branch| to a file. .. cli:synopsis:: @@ -15,8 +15,7 @@ Backup a |Gel| branch (or database pre-v5) to a file. Options ======= -The ``dump`` command creates a backup of the currently active database branch -or, in pre-v5 instances, the currently connected database. +The ``dump`` command creates a backup of the currently active database |branch|. For specifying the connection target see :ref:`connection options `. @@ -24,7 +23,7 @@ For specifying the connection target see :ref:`connection options The name of the file to backup the database branch into. :cli:synopsis:`--all` - Dump all branches (databases pre-v5) and the server configuration using the + Dump all |branches| and the server configuration using the directory specified by the :cli:synopsis:``. :cli:synopsis:`--format=` diff --git a/docs/cli/gel_instance/gel_instance_create.rst b/docs/cli/gel_instance/gel_instance_create.rst index 17d3ce73006..a82c6d77ff6 100644 --- a/docs/cli/gel_instance/gel_instance_create.rst +++ b/docs/cli/gel_instance/gel_instance_create.rst @@ -57,15 +57,16 @@ Options The new |Gel| instance name. Asked interactively if not specified. :cli:synopsis:`` - The default branch (or database pre-v5) name on the new instance. Defaults - to |main| or, when creating a pre-v5 instance, ``gel``. + The default |branch| name on the new instance. Defaults + to |main| or, when creating a pre-v5 instance, ``edgedb``. :cli:synopsis:`--nightly` Use the nightly server for this instance. :cli:synopsis:`--default-user=` Specifies the default user name (created during initialization, - and saved in credentials file). Defaults to: ``gel``. + and saved in credentials file). Defaults to: ``admin``, + or, when creating a pre-v6 instance, ``edgedb``. :cli:synopsis:`--port=` Specifies which port should the instance be configured on. By diff --git a/docs/cli/gel_list.rst b/docs/cli/gel_list.rst index 744345c2b2a..63c6339a0c3 100644 --- a/docs/cli/gel_list.rst +++ b/docs/cli/gel_list.rst @@ -31,9 +31,6 @@ Types :cli:synopsis:`gel list branches` Display list of branches. -:cli:synopsis:`gel list databases` - Display list of databases in the server instance. - :cli:synopsis:`gel list indexes` Display list of indexes defined in the schema. @@ -52,7 +49,7 @@ Types Options ======= -The ``list`` command runs in the database it is connected to. For +The ``list`` command runs in the |branch| it is connected to. For specifying the connection target see :ref:`connection options `. diff --git a/docs/cli/gel_migration/gel_migration_create.rst b/docs/cli/gel_migration/gel_migration_create.rst index 96f7098cab2..34f0efa0c2c 100644 --- a/docs/cli/gel_migration/gel_migration_create.rst +++ b/docs/cli/gel_migration/gel_migration_create.rst @@ -13,8 +13,8 @@ migration script. This is done by invoking the following command: gel migration create [] This will start an interactive tool that will provide the user with -suggestions based on the differences between the current branch (or database -for pre-v5) and the schema file. The prompts will look something like this: +suggestions based on the differences between the current |branch| +and the schema file. The prompts will look something like this: .. code-block:: diff --git a/docs/cli/gel_migration/index.rst b/docs/cli/gel_migration/index.rst index 9b79bb8cc7f..5a21efafd98 100644 --- a/docs/cli/gel_migration/index.rst +++ b/docs/cli/gel_migration/index.rst @@ -40,7 +40,7 @@ single SDL document. :class: funcoptable * - :ref:`ref_cli_gel_migration_apply` - - Bring current branch (or database pre-v5) to the latest or a specified revision + - Bring current |branch| to the latest or a specified revision * - :ref:`ref_cli_gel_migration_create` - Create a migration script * - :ref:`ref_cli_gel_migration_edit` diff --git a/docs/cli/gel_restore.rst b/docs/cli/gel_restore.rst index 77870760c6e..97eec08ed56 100644 --- a/docs/cli/gel_restore.rst +++ b/docs/cli/gel_restore.rst @@ -5,7 +5,7 @@ gel restore =========== -Restore a |Gel| branch from a backup file. +Restore a |Gel| |branch| from a backup file. .. cli:synopsis:: @@ -15,20 +15,20 @@ Restore a |Gel| branch from a backup file. Description =========== -:gelcmd:`restore` is a terminal command used to restore an Gel database -branch (or database pre-v5) from a backup file. The backup is restored to the -currently active branch (or to the currently connected database pre-v5). +:gelcmd:`restore` is a terminal command used to restore an Gel |branch| +|branch| from a backup file. The backup is restored to the +currently active branch. .. note:: - The backup cannot be restored to a branch (or database pre-v5) with any + The backup cannot be restored to a |branch| with any existing schema. As a result, you should restore to one of these targets: - - a new empty branch which can be created using + - a new empty |branch| which can be created using :ref:`ref_cli_gel_branch_create` with the ``--empty`` option - - a new empty database if your instance is running |EdgeDB| versions + - a new empty |branch| if your instance is running |EdgeDB| versions prior to 5 - - an existing branch or database that has been wiped with the appropriate + - an existing |branch| that has been wiped with the appropriate ``wipe`` command (either :ref:`ref_cli_gel_branch_wipe` or :ref:`ref_cli_gel_database_wipe`; note that this will destroy all data and schema currently in that branch/database) @@ -37,15 +37,15 @@ currently active branch (or to the currently connected database pre-v5). Options ======= -The ``restore`` command restores the backup file into the active branch or, in -pre-v5 instance, the currently connected database. For specifying the -connection target see :ref:`connection options `. +The ``restore`` command restores the backup file into the active |branch|. +For specifying the connection target see :ref:`connection options +`. :cli:synopsis:`` - The name of the backup file to restore the database branch from. + The name of the backup file to restore the |branch| from. :cli:synopsis:`--all` - Restore all branches (or databases pre-v5) and the server configuration + Restore all |branches| and the server configuration using the directory specified by the :cli:synopsis:``. :cli:synopsis:`-v, --verbose` diff --git a/docs/cli/gel_ui.rst b/docs/cli/gel_ui.rst index b0e43329299..2bd80fcab06 100644 --- a/docs/cli/gel_ui.rst +++ b/docs/cli/gel_ui.rst @@ -35,7 +35,7 @@ table. Options ======= -The ``ui`` command runs on the database it is connected to. For specifying the +The ``ui`` command runs on the |branch| it is connected to. For specifying the connection target see :ref:`connection options `. :cli:synopsis:`--print-url` diff --git a/docs/cli/gel_watch.rst b/docs/cli/gel_watch.rst index 9a3249a349f..afc372c7998 100644 --- a/docs/cli/gel_watch.rst +++ b/docs/cli/gel_watch.rst @@ -6,8 +6,8 @@ gel watch ========= Start a long-running process that watches for changes in schema files in your -project's ``dbschema`` directory and applies those changes to your database in -real time. Starting it is as simple as running this command: +project's ``dbschema`` directory and applies those changes to your current +|branch| in real time. Starting it is as simple as running this command: .. cli:synopsis:: diff --git a/docs/cli/index.rst b/docs/cli/index.rst index 6a71df32736..5749776e08d 100644 --- a/docs/cli/index.rst +++ b/docs/cli/index.rst @@ -138,22 +138,22 @@ The ``cli.toml`` has the following structure. All fields are optional: gel_connopts network gel - gel_analyze + gel_project/index + gel_ui + gel_watch + gel_migrate + gel_migration/index + gel_cloud/index gel_branch/index + gel_dump + gel_restore gel_configure + gel_query + gel_analyze + gel_list + gel_info gel_cli_upgrade - gel_cloud/index - gel_database/index + gel_server/index gel_describe/index - gel_dump - gel_info gel_instance/index - gel_list - gel_migrate - gel_migration/index - gel_project/index - gel_query - gel_restore - gel_server/index - gel_ui - gel_watch + gel_database/index diff --git a/docs/datamodel/index.rst b/docs/datamodel/index.rst index a8f29da50a8..bb61c06a3d6 100644 --- a/docs/datamodel/index.rst +++ b/docs/datamodel/index.rst @@ -126,7 +126,7 @@ your VCS. Each branch has its own schema and data. Module ^^^^^^ -Each branch (or database pre-v5) has a schema consisting of several +Each |branch| 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``. diff --git a/docs/stdlib/sys.rst b/docs/stdlib/sys.rst index 22da00a8737..19fafae432a 100644 --- a/docs/stdlib/sys.rst +++ b/docs/stdlib/sys.rst @@ -95,6 +95,11 @@ System Return the name of the current database as a string. + .. note:: + + This function is deprecated in |Gel|. + Use :eql:func:`sys::get_current_branch` instead. + .. code-block:: edgeql-repl db> select sys::get_current_database(); diff --git a/edb/tools/docs/edb.py b/edb/tools/docs/edb.py index decfd8fcfc1..7761d86ec33 100644 --- a/edb/tools/docs/edb.py +++ b/edb/tools/docs/edb.py @@ -150,8 +150,11 @@ def apply(self): # Traverse all substitution_reference nodes. for node in self.document.traverse(d_nodes.substitution_reference): nt = node.astext() - if nt in {"Gel", "Gel's","EdgeDB", "gelcmd", ".gel", "gel.toml", - "gel-server", "geluri", "admin", "main"}: + if nt.lower() in { + "gel", "gel's","edgedb", "gelcmd", ".gel", "gel.toml", + "gel-server", "geluri", "admin", "main", + "branch", "branches" + }: if builder_name in {"xml", "edge-xml"}: if nt == "gelcmd": sub = d_nodes.literal(