Document the CLI's migration extract command (#7169)

* Add missing `migration extract` command

* Replace manual migration file restore process

This can now link to the `migration extract` command instead

docs/cli/edgedb_migration/edgedb_migration_extract.rst

@@ -0,0 +1,40 @@
+.. _ref_cli_edgedb_migration_extract:
+
+
+========================
+edgedb migration extract
+========================
+
+Extract migration history from the database and write it to
+``/dbschema/migrations``. Useful when a direct DDL command has been used to
+change the schema and now ``edgedb migrate`` will not comply because the
+database migration history is ahead of the migration history inside
+``/dbschema/migrations``.
+
+This can also be useful if the migrations on the file system have been lost or
+deleted.
+
+Options
+=======
+
+The ``migration extract`` command runs on the database it is connected
+to. For specifying the connection target see :ref:`connection options
+<ref_cli_edgedb_connopts>`.
+
+
+:cli:synopsis:`--tls-server-name <TLS_SERVER_NAME>`
+    Override server name used for TLS connections and certificate verification.
+
+    Useful when the server hostname cannot be used as it does not resolve, or
+    resolves to a wrong IP address, and a different name or IP address is used
+    in ``--host``.
+
+:cli:synopsis:`--non-interactive`
+    Don't ask questions, only add missing files, abort if mismatching
+
+:cli:synopsis`--force`
+    Force overwrite existing migration files
+
+:cli:synopsis:`--schema-dir=<schema-dir>`
+    Directory where the schema files are located. Defaults to
+    ``./dbschema``.

docs/cli/edgedb_migration/index.rst

@@ -18,6 +18,7 @@ Using the migration tools is the recommended way to make schema changes.
     edgedb_migration_apply
     edgedb_migration_create
     edgedb_migration_edit
+    edgedb_migration_extract
     edgedb_migration_log
     edgedb_migration_status
     edgedb_migration_upgrade_check
@@ -44,6 +45,8 @@ single SDL document.
       - Create a migration script
     * - :ref:`ref_cli_edgedb_migration_edit`
       - Edit migration file
+    * - :ref:`ref_cli_edgedb_migration_extract`
+      - Extract migration history and write it to ``/migrations``.
     * - :ref:`ref_cli_edgedb_migration_log`
       - Show all migration versions
     * - :ref:`ref_cli_edgedb_migration_status`

docs/guides/migrations/tips.rst

@@ -1335,65 +1335,9 @@ After removing the bugged ``Character``, we can migrate without any problems:
 Recovering lost migrations
 --------------------------
 
-Each time you create a migration with :ref:`ref_cli_edgedb_migration_create`,
-a file containing the DDL for that migration is created in
-``dbschema/migrations``. When you apply a migration with
-:ref:`ref_cli_edgedb_migration_apply` or :ref:`ref_cli_edgedb_migrate`, the
-database stores a record of the migration it applied.
-
-On rare occasions, you may find you have deleted your migration files by
-mistake. If you don't care about any of your data and don't need to keep your
-migration history, you can :ref:`wipe <ref_cli_edgedb_database_wipe>` your
-database and start over, creating a single migration to the current state of
-your schema. If that's not an option, all hope is not lost. You can instead
-recover your migrations from the database.
-
-Run this query to see your migrations:
-
-.. code-block:: edgeql
-
-    select schema::Migration {
-      name,
-      script,
-      parents: {name}
-    }
-
-You can rebuild your migrations from the results of this query, either manually
-or via a script if you've applied too many of them to recreate by hand.
-Migrations in the file system are named sequentially starting from
-``00001.edgeql``. They are in this format:
-
-.. code-block:: edgeql
-
-    CREATE MIGRATION m1rsm66e5pvh5ets2yznutintmqnxluzvgbocspi6umd3ht64e4naq
-                     # ☝️ Replace with migration name
-        ONTO m1l5esbbycsyqcnx6udxx24riavvyvkskchtekwe7jqx5mmiyli54a
-             # ☝️ Replace with parent migration name
-    {
-      # script
-      # ☝️ Replace with migration script
-    };
-
-or if this is the first migration:
-
-.. code-block:: edgeql
-
-    CREATE MIGRATION m1l5esbbycsyqcnx6udxx24riavvyvkskchtekwe7jqx5mmiyli54a
-                     # ☝️ Replace with migration name
-        ONTO initial
-    {
-      # script
-      # ☝️ Replace with migration script
-    };
-
-Replace the name, script, and parent name with the values from
-your ``Migration`` query results.
-
-You can identify the first migration in your query results as the one with no
-object linked on ``parents``. Order the other migrations by chaining the links.
-The ``Migration`` with the initial migration linked via ``parents`` is the
-second migration — ``00002.edgeql``. The migration linking to the second
-migration via ``parents`` is the third migration, and so on).
+You can recover lost migration files, writing the database's current
+migration history to ``/dbschema/migrations`` by using the
+:ref:`ref_cli_edgedb_migration_extract`.
 
 Getting the current migration
 -----------------------------