Merge pull request #28692 from angeliski/add-rollback-tutorial

docs: add new tutorial to knex rollback

docs/getting-started/config/database.md

@@ -168,5 +168,6 @@ We recommend you read [Setting up authentication](./authentication.md) next.
 If you want to read more about the database configuration, here are some helpful links:
 
 - [Configuring Plugin Databases](../../tutorials/configuring-plugin-databases.md#privileges)
+- [Manual Knex Rollback](../../tutorials/manual-knex-rollback.md)
 - [Read more about Knex](http://knexjs.org/), the database wrapper that we use.
 - [Install `pgAdmin` 4](https://www.pgadmin.org/), a helpful tool for querying your database.

docs/getting-started/keeping-backstage-updated.md

@@ -160,3 +160,7 @@ export GLOBAL_AGENT_NO_PROXY=${NO_PROXY}
 export YARN_HTTP_PROXY=${HTTP_PROXY}                          # optional
 export YARN_HTTPS_PROXY=${HTTPS_PROXY}                        # optional
 ```
+
+## Rollback migrations
+
+In some cases you could need to downgrade Backstage instance due to some problem or maybe because you are using a test environment to validate the new version of Backstage. You can check the [Manual Rollback using Knex](../tutorials/manual-knex-rollback.md) guide to know how to rollback migrations using Knex.

docs/tutorials/configuring-plugin-databases.md

@@ -181,3 +181,11 @@ GRANT SHOW DATABASES ON *.* TO some_user;
 
 The mechanisms in this guide should help you tackle different database
 deployment situations. Good luck!
+
+## Further Reading
+
+If you want to read more about the database configuration, here are some helpful links:
+
+- [Manual Knex Rollback](./manual-knex-rollback.md)
+- [Read more about Knex](http://knexjs.org/), the database wrapper that we use.
+- [Install `pgAdmin` 4](https://www.pgadmin.org/), a helpful tool for querying your database.

docs/tutorials/manual-knex-rollback.md

@@ -0,0 +1,61 @@
+---
+id: manual-knex-rollback
+title: Manual Rollback using Knex
+# prettier-ignore
+description: Guide on how to rollback Knex migrations.
+---
+
+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.
+
+You are likely to receive a message like this when you try a downgrade without the rollback:
+
+```sh
+Backend failed to start up Error: The migration directory is corrupt, the following files are missing: 20230428155633_sessions.js
+```
+
+Currently, we don't have a simple way to check which migrations and which plugins have been applied in the database, but you can follow this [issue](https://github.com/backstage/backstage/issues/22439) to get more information about this.
+This guide covers a simple way to rollback migrations using Knex. We have plans to support this in Backstage's CLI ([issue](https://github.com/backstage/backstage/issues/6366)), but for now it is possible to use Knex CLI to manage migrations in necessary cases.
+
+To start, you are going to need two things: database access and the plugin migrations directory you want to handle. We are going to use environment variables to access the database and we'll be using the `@backstage/plugin-catalog-backend` plugin 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 handles Databases in [Configuring Plugin Databases](./configuring-plugin-databases.md). This tutorial follows the information in the [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 commands below in the project root:
+
+We want to check the migration status:
+
+```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 2 Completed Migration file/files.
+20211229105307_init.js
+20240113144027_assets-namespace.js
+No Pending Migration files Found.
+```
+
+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
+```
+
+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 use `migrate:currentVersion` which retrieves the current migration version. If there aren't any migrations run yet, it will return "none".
+
+```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
+```

microsite/sidebars.js

@@ -498,6 +498,7 @@ module.exports = {
         Technical: [
           'tutorials/quickstart-app-plugin',
           'tutorials/configuring-plugin-databases',
+          'tutorials/manual-knex-rollback',
           'tutorials/switching-sqlite-postgres',
           'tutorials/using-backstage-proxy-within-plugin',
           'tutorials/enable-public-entry',

mkdocs.yml

@@ -211,6 +211,7 @@ nav:
       - Package Role Migration: 'tutorials/package-role-migration.md'
       - Migrating away from @backstage/core: 'tutorials/migrating-away-from-core.md'
       - Adding Custom Plugin to Existing Monorepo App: 'tutorials/quickstart-app-plugin.md'
+      - Manual Rollback using Knex: 'tutorials/manual-knex-rollback.md'
       - Switching Backstage from SQLite to PostgreSQL: 'tutorials/switching-sqlite-postgres.md'
       - Using the Backstage Proxy from Within a Plugin: 'tutorials/using-backstage-proxy-within-plugin.md'
       - Migration to Yarn 3: 'tutorials/yarn-migration.md'