diff --git a/docs/guides/migrations/guide.rst b/docs/guides/migrations/guide.rst index e48369beffb..d2c8b19d4cf 100644 --- a/docs/guides/migrations/guide.rst +++ b/docs/guides/migrations/guide.rst @@ -646,9 +646,9 @@ Fixups during a squash If your schema doesn't match the schema in the database, EdgeDB will prompt you to create a *fixup* file, which can be useful to, as the CLI says, "automate upgrading other instances to a squashed revision". -You'll see fixups inside a folder called ``/fixups``. Their file names -are extremely long, but are simply two migration hashes joined together -by a dash. So a fixup that begins with +You'll see fixups inside ``/dbschema/fixups``. Their file names +are extremely long because they are simply two migration hashes joined together +by a dash. This means a fixup that begins with .. code-block:: @@ -660,9 +660,7 @@ will have a file name a full 116 characters in length. The CLI output when using squash along with a fixup is pretty informative on its own, so let's just walk through the output as you'll see it -in practice. - -First we'll begin with this schema: +in practice. First we'll begin with this schema: .. code-block:: sdl @@ -674,7 +672,7 @@ Then remove ``name: str;`` from the ``User`` type, migrate, put it back again, and migrate. You'll now have multiple files in your ``/migrations`` folder and will now be able to squash them. -Then change to this schema without migrating it: +Then change to this schema **without migrating it**: .. code-block:: sdl @@ -683,7 +681,7 @@ Then change to this schema without migrating it: nickname: str; } -Upon using ``edgedb migration create --squash``, the output is first +Now run ``edgedb migration create --squash``. The output is first the same as with our previous squash: .. code-block:: bash @@ -722,7 +720,7 @@ differs from what you have and offers to make a fixup file: Create a fixup file? [y/n] > y -You will then see the the same questions that otherwise show up in +You will then see the the same questions that would otherwise show up in a standard migration: .. code-block:: @@ -744,6 +742,10 @@ working with git after doing a squash with a fixup. The normal migration process will update your migration history: edgedb migrate +We'll take its suggestion to apply the migration: + +.. code-block:: bash + $ edgedb migrate Applied m1v3vqmwif4ml3ucbzi555mjgm4myxs2husqemopo2sz2m7otr22ka @@ -753,7 +755,7 @@ working with git after doing a squash with a fixup. .. note:: - Squashing is still limited to schema changes, so queries inside + Squashing is limited to schema changes, so queries inside data migrations will be discarded during a squash. EdgeDB Watch @@ -761,7 +763,7 @@ EdgeDB Watch Another option when quickly iterating over schema changes is ``edgedb watch``. This will create a long-running process that keeps track of every time you -save as ``.esdl`` file inside your ``/migrations`` folder, letting you know +save an ``.esdl`` file inside your ``/migrations`` folder, letting you know if your changes have successfully compiled or not. The command itself will lead to the following input ``edgedb watch`` starts up: @@ -830,16 +832,16 @@ can't be resolved: Schema migration error: cannot proceed until .esdl files are fixed -Once you correct the ``i32`` property to ``int32``, EdgeDB Watch will -let you know that things are okay now, and will become quiet again: +Once you correct the ``i32`` type to ``int32``, EdgeDB Watch will +let you know that things are okay now and will resume quietly watching your schema and applying migrations: .. code-block:: Resolved. Schema is up to date now. -EdgeDB Watch is best run in a separate tab on your command line so -that you can take care of other tasks—including officially migrating -when you are satisfied with your current schema—without having to +EdgeDB Watch is best run in a separate instance of your command line so +that you can take care of other tasks — including officially migrating +when you are satisfied with your current schema — without having to stop the process. If you are curious what is happening as EdgeDB Watch does its thing, @@ -856,18 +858,20 @@ Some migrations will contain nothing in their ``generated_by`` property, while those generated by EdgeDB Watch will have a ``MigrationGeneratedBy.DevMode``. -(The final option for ``generated_by`` is -``MigrationGeneratedBy.DDLStatement``, which will show up if you directly -change your schema by using DDL - which is generally not recommended) +.. note:: + + The final option (aside from ``DevMode`` and the empty set) for ``generated_by`` is + ``MigrationGeneratedBy.DDLStatement``, which will show up if you directly + change your schema by using DDL, which is generally not recommended. Once you are satisfied with your changes while running EdgeDB Watch, just create the migration with ``edgedb migration create`` and then -apply them with one small change: ``edgedb migrate --dev-mode`` to +apply them with one small tweak to the ``migrate`` command: ``edgedb migrate --dev-mode`` to let the CLI know to apply the migrations made during dev mode that were made by EdgeDB Watch. -So you really want to use DDL -============================= +So, you really want to use DDL? +=============================== You might have a good reason to use a direct DDL statement or two to change your schema. How do you make that happen? EdgeDB disables @@ -889,7 +893,7 @@ the usage of DDL by default, so this attempt to use DDL will not work: migration flow. This configuration can be overridden by the following command which -changes the enum ``allow_bare_ddl``from the default ``NeverAllow`` +changes the enum ``allow_bare_ddl`` from the default ``NeverAllow`` to the other option, ``AlwaysAllow``. .. code-block:: edgeql-repl @@ -900,8 +904,8 @@ Note that the command is ``configure current database`` and not ``configure instance``, as ``allow_bare_ddl`` is evaluated on the database level. That wasn't so bad, so why did the CLI tell us to try to "avoid accidental -schema changes outside of the migration flow"? Why is DDL disabled -by default in the first place? +schema changes outside of the migration flow?" Why is DDL disabled +after running a migration in the first place? So you really wanted to use DDL but now regret it =================================================