From 02edb51464b4d1b2bfb1e474475df0692799f897 Mon Sep 17 00:00:00 2001 From: Victor Petrovykh Date: Tue, 25 Feb 2025 05:35:23 -0500 Subject: [PATCH] Update the `gel.toml` description. Add `[hooks]` and `[[watch]]` documentation. Update the docs for the `gel watch` command as well. --- docs/reference/cli/gel_watch.rst | 50 +++++++++---- docs/reference/reference/gel_toml.rst | 100 +++++++++++++++++++++++++- 2 files changed, 137 insertions(+), 13 deletions(-) diff --git a/docs/reference/cli/gel_watch.rst b/docs/reference/cli/gel_watch.rst index fd66845c901..1034a5d98e1 100644 --- a/docs/reference/cli/gel_watch.rst +++ b/docs/reference/cli/gel_watch.rst @@ -5,25 +5,51 @@ 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 current -|branch| in real time. Starting it is as simple as running this command: +Start a long-running process that watches for changes as specified in the +:ref:`gel.toml ` file. This process will monitor the +project for changes specified in the ``[[watch]]`` table array and run the +associated scripts in response to those changes. + +When multiple changes target the same ``[[watch]]`` element, the corresponding +script will be triggered only once. All triggered watch scripts will be +executed in parallel. If the same script is triggered before it finishes +executing, the next execution will wait for the already running script to +terminate (i.e. only one instance of the same script will be runing at the +same time). -.. cli:synopsis:: +.. note:: - gel watch + Any output that the triggered scripts produce will be shown in the + :gelcmd:`watch` console. This includes any error messages. So if you're + not seeing a change you've expected, check on the watch process to make + sure there aren't any unexpected errors in the triggered scripts. -.. note:: +To learn about our recommended development migration workflow using +:gelcmd:`watch`, read our :ref:`intro to migrations `. + +Options +======= + +.. warning:: + + This command changed in version 6. In older versions it only monitored the + schema file changes and it had no additional options. + +.. versionadded:: 6.0 + +:cli:synopsis:`--migrate` + Watches for changes in schema files in your project's ``dbschema`` + directory and applies those changes to your current |branch| in real time. If a schema change cannot be applied, you will see an error in the :gelcmd:`watch` console. You will also receive the error when you try to run a query with any |Gel| client binding. -To learn about our recommended development migration workflow using -:gelcmd:`watch`, read our :ref:`intro to migrations `. + .. note:: -.. note:: + If you want to apply a migration in the same manner as ``watch + --migrate`` but without the long-running process, use :gelcmd:`migrate + --dev-mode`. See :ref:`ref_cli_gel_migration_apply` for more details. - If you want to apply a migration in the same manner as ``watch`` but - without the long-running process, use :gelcmd:`migrate --dev-mode`. See - :ref:`ref_cli_gel_migration_apply` for more details. +:cli:synopsis:`-v, --verbose` + Verbose output. diff --git a/docs/reference/reference/gel_toml.rst b/docs/reference/reference/gel_toml.rst index bda4e47562c..bee9e0a4c9f 100644 --- a/docs/reference/reference/gel_toml.rst +++ b/docs/reference/reference/gel_toml.rst @@ -7,7 +7,7 @@ gel.toml The |gel.toml| file is created in the project root after running :ref:`ref_cli_gel_project_init`. If this file is present in a directory, it signals to the CLI and client bindings that the directory is an instance-linked -|Gel| project. It supports two configuration settings across two tables: +|Gel| project. It supports the following configuration settings: .. note:: @@ -45,6 +45,91 @@ signals to the CLI and client bindings that the directory is an instance-linked Defaults to ``dbschema``. +[hooks] table +============= + +.. versionadded:: 6 + +This table may contain the following keys, all of which are optional: + +- ``project.init.before`` +- ``project.init.after`` +- ``branch.switch.before`` +- ``branch.wipe.before`` +- ``migration.apply.before`` +- ``schema.update.before`` +- ``branch.switch.after`` +- ``branch.wipe.after`` +- ``migration.apply.after`` +- ``schema.update.after`` + +Each key represents a command hook that will be executed together with a CLI +command. All keys have a string value which is going to be executed as a shell +command when the corresponding hook is triggered. + +Hooks are divided into two categories: ``before`` and ``after`` as indicated +by their names. All of the ``before`` hooks are executed prior to their +corresponding commands, so they happen before any changes are made. All of the +``after`` hooks run after the CLI command and thus the effects from the +command are already in place. Any error during the hook script execution will +terminate the CLI command (thus ``before`` hooks are able to prevent their +commands from executing if certain conditions are not met). + +Overall, when multiple hooks are triggered they all execute sequentially in +the order they are listed above. + +Here is a breakdown of which command trigger which hooks: + +- :ref:`ref_cli_gel_project_init` command triggers the ``project.init.before`` + and ``project.init.after`` hook. If the migrations are applied at the end of + the initialization, then the ``migration.apply.before``, + ``schema.update.before``, ``migration.apply.after``, and + ``schema.update.after`` hooks are also triggered. +- :ref:`ref_cli_gel_branch_switch` command triggers ``branch.switch.before``, + ``schema.update.before``, ``branch.switch.after``, and ``schema.update.after`` + hooks in that relative order. +- :ref:`ref_cli_gel_branch_wipe` command triggers the ``branch.wipe.before``, + ``schema.update.before``, ``branch.wipe.after``, and ``schema.update.after`` + hooks in that relative order. +- :ref:`ref_cli_gel_branch_rebase` and :ref:`ref_cli_gel_branch_merge` + commands trigger ``migration.apply.before``, ``schema.update.before``, + ``migration.apply.after``, and ``schema.update.after`` hooks in that + relative order. Notice that although these are branch commands, but they do + not change the current branch, instead they modify and apply migrations. + That's why they trigger the ``migration.apply`` hooks. +- :ref:`ref_cli_gel_migration_apply` command triggers + ``migration.apply.before``, ``schema.update.before``, + ``migration.apply.after``, and ``schema.update.after`` hooks in that + relative order. + + .. note:: + + All of these hooks are intended as project management tools. For this + reason they will only be triggered by the CLI commands that *don't + override* default project settings. Any CLI command that uses + :ref:`connection options ` will not trigger any + hooks. + +This is implementing `RFC 1028 `_. + +[[watch]] table array +===================== + +.. versionadded:: 6 + +Each element of this table array may contain the following required keys: + +- ``files = ["", ...]`` - specify file(s) being watched. + + The paths must use ``/`` (\*nix-style) as path separators. They can also contain glob pattrens (``*``, ``**``, ``?``, etc.) in order to specify multiple files at one. + +- ``script = ""`` - command to be executed by the shell. + +The watch mode can be activated by the :ref:`ref_cli_gel_watch` command. + +This is implementing `RFC 1028 `_. + + Example ======= @@ -56,9 +141,22 @@ Example [project] schema-dir = "db/schema" + [hooks] + project.init.after="setup_dsn.sh" + branch.wipe.after="" + branch.switch.after="setup_dsn.sh" + schema.update.after="gel-orm sqlalchemy --mod compat --out compat" + + [[watch]] + files = ["queries/*.edgeql"] + script = "npx @edgedb/generate queries" + .. lint-off .. _all of the same version specifications as Cargo: https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies +.. _rfc1028: + https://github.com/edgedb/rfcs/blob/master/text/1028-cli-hooks.rst + .. lint-on