From 10691ea92a2f188c4c3aa3927ee099a5277028c9 Mon Sep 17 00:00:00 2001 From: Rogerio Angeliski Date: Fri, 31 Jan 2025 09:54:50 -0300 Subject: [PATCH 1/7] docs: add new tutorial to knex rollback Signed-off-by: Rogerio Angeliski --- docs/getting-started/config/database.md | 1 + .../keeping-backstage-updated.md | 4 ++ .../tutorials/configuring-plugin-databases.md | 8 +++ docs/tutorials/manual-knex-rollback.md | 52 +++++++++++++++++++ microsite/sidebars.js | 1 + mkdocs.yml | 1 + 6 files changed, 67 insertions(+) create mode 100644 docs/tutorials/manual-knex-rollback.md diff --git a/docs/getting-started/config/database.md b/docs/getting-started/config/database.md index 699160d550..ecf461f02a 100644 --- a/docs/getting-started/config/database.md +++ b/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. diff --git a/docs/getting-started/keeping-backstage-updated.md b/docs/getting-started/keeping-backstage-updated.md index b31409cfc2..948fa9c273 100644 --- a/docs/getting-started/keeping-backstage-updated.md +++ b/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](./manual-knex-rollback.md) guide to know how to rollback migrations using Knex. diff --git a/docs/tutorials/configuring-plugin-databases.md b/docs/tutorials/configuring-plugin-databases.md index db3f126de7..264845a99c 100644 --- a/docs/tutorials/configuring-plugin-databases.md +++ b/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](../../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. diff --git a/docs/tutorials/manual-knex-rollback.md b/docs/tutorials/manual-knex-rollback.md new file mode 100644 index 0000000000..7a6a57221f --- /dev/null +++ b/docs/tutorials/manual-knex-rollback.md @@ -0,0 +1,52 @@ +--- +id: manual-knex-rollback +title: Manual Rollback using Knex +# prettier-ignore +description: Guide on how to rollback Knex migrations. +--- + +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: 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: + +```sh +# we want to check the migration status +$ node_modules/.bin/knex --connection "postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@$POSTGRES_HOST/backstage_plugin_app" --client pg --migrations-directory node_modules/@backstage/plugin-catalog-backend/migrations/ migrate:status +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 +$ node_modules/.bin/knex --connection "postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@$POSTGRES_HOST/backstage_plugin_app" --client pg --migrations-directory node_modules/@backstage/plugin-catalog-backend/migrations/ migrate:down 20240113144027_assets-namespace.js +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 +$ node_modules/.bin/knex --connection "postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@$POSTGRES_HOST/backstage_plugin_app" --client pg --migrations-directory node_modules/@backstage/plugin-catalog-backend/migrations/ migrate:status +Using environment: production +Found 1 Completed Migration file/files. +20211229105307_init.js +Found 1 Pending Migration file/files. +20240113144027_assets-namespace.js + + +# running migrations to the current version +$ 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. You are likely to receive a message like this: + +```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. diff --git a/microsite/sidebars.js b/microsite/sidebars.js index 46240cb649..c6b42f9056 100644 --- a/microsite/sidebars.js +++ b/microsite/sidebars.js @@ -498,6 +498,7 @@ module.exports = { Techical: [ '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', diff --git a/mkdocs.yml b/mkdocs.yml index a7e693e5fc..f91d8ff735 100644 --- a/mkdocs.yml +++ b/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' From f4a3879060fc3132770f26282bf25fc8926e9639 Mon Sep 17 00:00:00 2001 From: Rogerio Angeliski Date: Fri, 31 Jan 2025 11:13:23 -0300 Subject: [PATCH 2/7] docs: update with review comments Signed-off-by: Rogerio Angeliski --- docs/tutorials/manual-knex-rollback.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/tutorials/manual-knex-rollback.md b/docs/tutorials/manual-knex-rollback.md index 7a6a57221f..39f01882d4 100644 --- a/docs/tutorials/manual-knex-rollback.md +++ b/docs/tutorials/manual-knex-rollback.md @@ -14,7 +14,7 @@ You can interact with Knex running the following in the project root: ```sh # we want to check the migration status -$ node_modules/.bin/knex --connection "postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@$POSTGRES_HOST/backstage_plugin_app" --client pg --migrations-directory node_modules/@backstage/plugin-catalog-backend/migrations/ migrate: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 @@ -22,13 +22,13 @@ Found 2 Completed Migration file/files. No Pending Migration files Found. # we want to rollback a specific migration called 20240113144027_assets-namespace.js -$ node_modules/.bin/knex --connection "postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@$POSTGRES_HOST/backstage_plugin_app" --client pg --migrations-directory node_modules/@backstage/plugin-catalog-backend/migrations/ migrate:down 20240113144027_assets-namespace.js +$ 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 -$ node_modules/.bin/knex --connection "postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@$POSTGRES_HOST/backstage_plugin_app" --client pg --migrations-directory node_modules/@backstage/plugin-catalog-backend/migrations/ migrate: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 1 Completed Migration file/files. 20211229105307_init.js @@ -37,13 +37,15 @@ Found 1 Pending Migration file/files. # running migrations to the current version -$ node_modules/.bin/knex migrate:currentVersion --connection "postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@$POSTGRES_HOST/backstage_plugin_app" --client pg +$ 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. You are likely to receive a message like this: +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 From 0a541453451f165c70b68545aac00f151d84a75a Mon Sep 17 00:00:00 2001 From: Rogerio Angeliski Date: Fri, 31 Jan 2025 11:35:00 -0300 Subject: [PATCH 3/7] docs: fix tutorial link Signed-off-by: Rogerio Angeliski --- docs/getting-started/keeping-backstage-updated.md | 2 +- docs/tutorials/configuring-plugin-databases.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/keeping-backstage-updated.md b/docs/getting-started/keeping-backstage-updated.md index 948fa9c273..a44cb3c8bc 100644 --- a/docs/getting-started/keeping-backstage-updated.md +++ b/docs/getting-started/keeping-backstage-updated.md @@ -163,4 +163,4 @@ 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](./manual-knex-rollback.md) guide to know how to rollback migrations using Knex. +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. diff --git a/docs/tutorials/configuring-plugin-databases.md b/docs/tutorials/configuring-plugin-databases.md index 264845a99c..c6d9869d38 100644 --- a/docs/tutorials/configuring-plugin-databases.md +++ b/docs/tutorials/configuring-plugin-databases.md @@ -186,6 +186,6 @@ deployment situations. Good luck! If you want to read more about the database configuration, here are some helpful links: -- [Manual Knex Rollback](../../tutorials/manual-knex-rollback.md) +- [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. From 17aa9532d2a6a2f0076e0ee90263d3be2f3d4fe1 Mon Sep 17 00:00:00 2001 From: Rogerio Angeliski Date: Tue, 4 Feb 2025 08:26:17 -0300 Subject: [PATCH 4/7] Update docs/tutorials/manual-knex-rollback.md Co-authored-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com> Signed-off-by: Rogerio Angeliski --- docs/tutorials/manual-knex-rollback.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/manual-knex-rollback.md b/docs/tutorials/manual-knex-rollback.md index 39f01882d4..a727c0a4c6 100644 --- a/docs/tutorials/manual-knex-rollback.md +++ b/docs/tutorials/manual-knex-rollback.md @@ -5,7 +5,7 @@ title: Manual Rollback using Knex description: Guide on how to rollback Knex migrations. --- -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. +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: 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. From 0aa129f855383f95e6a266614ac4698037d2adf9 Mon Sep 17 00:00:00 2001 From: Rogerio Angeliski Date: Tue, 4 Feb 2025 08:36:27 -0300 Subject: [PATCH 5/7] docs: update tutorial to split commands Signed-off-by: Rogerio Angeliski --- 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. From bc758b0fc8f64f6f7170628b848fc416e44e82c6 Mon Sep 17 00:00:00 2001 From: Rogerio Angeliski Date: Thu, 6 Feb 2025 21:00:12 -0300 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> Signed-off-by: Rogerio Angeliski --- docs/tutorials/manual-knex-rollback.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/manual-knex-rollback.md b/docs/tutorials/manual-knex-rollback.md index b382dc247e..bb0aaa7054 100644 --- a/docs/tutorials/manual-knex-rollback.md +++ b/docs/tutorials/manual-knex-rollback.md @@ -7,8 +7,8 @@ description: Guide on how to rollback Knex migrations. 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: 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. +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: @@ -43,7 +43,7 @@ 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 +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 From 0ecf0c44ded09c0f921c6a3fdada298d107685fc Mon Sep 17 00:00:00 2001 From: Rogerio Angeliski Date: Thu, 6 Feb 2025 21:01:49 -0300 Subject: [PATCH 7/7] docs: move use case section to the top Signed-off-by: Rogerio Angeliski --- docs/tutorials/manual-knex-rollback.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/tutorials/manual-knex-rollback.md b/docs/tutorials/manual-knex-rollback.md index bb0aaa7054..14e00d6659 100644 --- a/docs/tutorials/manual-knex-rollback.md +++ b/docs/tutorials/manual-knex-rollback.md @@ -5,6 +5,15 @@ title: Manual Rollback using Knex 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. @@ -50,13 +59,3 @@ $ node_modules/.bin/knex migrate:currentVersion --connection "postgresql://$POST 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. - -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.