From 0aa129f855383f95e6a266614ac4698037d2adf9 Mon Sep 17 00:00:00 2001
From: Rogerio Angeliski <angeliski@hotmail.com>
Date: Tue, 4 Feb 2025 08:36:27 -0300
Subject: [PATCH] docs: update tutorial to split commands

Signed-off-by: Rogerio Angeliski <angeliski@hotmail.com>
---
 docs/tutorials/manual-knex-rollback.md | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/docs/tutorials/manual-knex-rollback.md b/docs/tutorials/manual-knex-rollback.md
index a727c0a4c6..b382dc247e 100644
--- a/docs/tutorials/manual-knex-rollback.md
+++ b/docs/tutorials/manual-knex-rollback.md
@@ -10,37 +10,45 @@ This guide covers a simple way to rollback migrations using Knex. We have plans
 To start, you are going to need two things: the database access and the plugin migrations directory you want to handle. We are going to use environment variables to handle the database access and the `@backstage/plugin-catalog-backend` as an example. In most cases, there is a `migrations` directory in the root of the plugin package, but you can check the `package.json` file to confirm the directory.
 You can get more information about how Backstage handle Databases in [Configuring Plugin Databases](./configuring-plugin-databases.md). This tutorial follows the information in [Knex migration guide](https://knexjs.org/guide/migrations.html), so you can get more details about the commands there.
 
-You can interact with Knex running the following in the project root:
+You can interact with Knex running the commands below in the project root:
+
+We want to check the migration status:
 
 ```sh
-# we want to check the migration status
 $ node_modules/.bin/knex migrate:status --connection "postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@$POSTGRES_HOST/backstage_plugin_app" --client pg --migrations-directory node_modules/@backstage/plugin-catalog-backend/migrations/
 Using environment: production
 Found 2 Completed Migration file/files.
 20211229105307_init.js
 20240113144027_assets-namespace.js
 No Pending Migration files Found.
+```
 
-# we want to rollback a specific migration called 20240113144027_assets-namespace.js
+Now lets rollback a specific migration called `20240113144027_assets-namespace.js`:
+
+```sh
 $ node_modules/.bin/knex migrate:down 20240113144027_assets-namespace.js --connection "postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@$POSTGRES_HOST/backstage_plugin_app" --client pg --migrations-directory node_modules/@backstage/plugin-catalog-backend/migrations/
 Using environment: production
 Batch 2 rolled back the following migrations:
 20240113144027_assets-namespace.js
+```
 
-# we want to check the migration status to confirm we rolled back the migration
+Now we can check the migration status again to confirm the rollback:
+
+```sh
 $ node_modules/.bin/knex migrate:status --connection "postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@$POSTGRES_HOST/backstage_plugin_app" --client pg --migrations-directory node_modules/@backstage/plugin-catalog-backend/migrations/
 Using environment: production
 Found 1 Completed Migration file/files.
 20211229105307_init.js
 Found 1 Pending Migration file/files.
 20240113144027_assets-namespace.js
+```
 
+Now lets call `currentVersion` to retrieves and returns the current migration version, as a promise. If there aren't any migrations run yet, returns "none" as the value for the currentVersion
 
-#  running migrations to the current version
+```sh
 $ node_modules/.bin/knex migrate:currentVersion --connection "postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@$POSTGRES_HOST/backstage_plugin_app" --client pg
 Using environment: production
 Current Version: 20240113144027
-
 ```
 
 The most common case to use Knex directly is when you want to **rollback a migration** that was applied when you upgraded your Backstage instance and want to downgrade due to some problem. You can use the `migrate:down` command to rollback a specific migration. You can also use the `migrate:rollback` command to rollback the last batch of migrations. This is necessary because Knex will mark migrations as corrupted if you try to downgrade your Backstage instance without the rollback. Be aware to run those commands in the new version of the Backstage instance, so you can avoid the corrupted migrations for lower versions.