From cc46984eea61d938a7e0bc3aa63629593ae49c26 Mon Sep 17 00:00:00 2001 From: natehessler Date: Mon, 3 Nov 2025 10:18:38 -0600 Subject: [PATCH] Revise privileged migrations documentation After discussions with Marc (LeBlanc), updated the documentation for privileged migrations; removed the section on the `--noop-privileged` flag as this basically is never used. --- docs/admin/how-to/privileged_migrations.mdx | 32 +-------------------- 1 file changed, 1 insertion(+), 31 deletions(-) diff --git a/docs/admin/how-to/privileged_migrations.mdx b/docs/admin/how-to/privileged_migrations.mdx index 6c7555b1a..bc5dfba5f 100644 --- a/docs/admin/how-to/privileged_migrations.mdx +++ b/docs/admin/how-to/privileged_migrations.mdx @@ -6,7 +6,7 @@ If your Sourcegraph instance does not connect to the database with a superuser, Note that these flags affect the `migrator` commands `up`, `upto`, `downto`, `upgrade`, and `downgrade`. -## Option 1: `--unprivileged-only` +## `--unprivileged-only` Add the optional flag `--unprivileged-only` when [running the migrator](/admin/updates/migrator/migrator-operations) against your Postgres instance. When the migration runner encounters an unapplied privileged migration, it will halt with an error message similar to the following. @@ -18,33 +18,3 @@ The migration runner is currently being run with -unprivileged-only. The indicat This option is used to fail-fast upgrades that require manual user intervention. To allow the migrator to make additional progress, the privileged query/queries must be applied manually with a superuser (most commonly via a psql shell attached to the Postgres instance). To be interactively instructed through the manual process, re-run the migrator with the [`--noop-privileged`](#option-2-noop-privileged) flag. Otherwise, you can manually [find and apply the target privileged migrations](/admin/how-to/dirty_database#2-run-the-sql-queries-to-finish-incomplete-migrations) and [manually add a migration log entry](/admin/how-to/dirty_database#3-add-a-migration-log-entry). - -## Option 2: `--noop-privileged` - -Add the optional flag `--noop-privileged` when [running the migrator](/admin/updates/migrator/migrator-operations) against your Postgres instance. When the migration runner encounters an unapplied privileged migration, it will initially halt with an error message similar to the following. - -``` -❌ failed to run migration for schema "frontend": refusing to apply a privileged migration: apply the following SQL and re-run with the added flag `--privileged-hash=vp6EzmVmJfHgfchaShhJPUCq5v4=` to continue. -``` - -```sql -BEGIN; --- Migration 1657908958 -COMMENT ON EXTENSION citext IS 'first privileged migration'; --- Migration 1657908965 -COMMENT ON EXTENSION citext IS 'second privileged migration'; -COMMIT; -``` - -Manually apply the provided SQL with superuser access in the target schema. Then re-invoke the migrator with the suggested flag (e.g., `-privileged-hash=vp6EzmVmJfHgfchaShhJPUCq5v4=`). This value is unique to the set of privileged migration definitions and ensures that you have followed the instructions specific to this installation or upgrade. - -The migrator may print multiple such error messages for different schemas that contain privileged migrations. In this case, multiple `-privileged-hash` flags are expected on the same re-invocation of the migrator. - -Re-running the migrator should then succeed, skipping each of the migrations which were just manually applied. - -``` -WARN migrations.runner runner/run.go:309 The migrator assumes that the following SQL queries have already been applied. Failure to have done so may cause the following operation to fail. {"schema": "frontend", "sql": "BEGIN;\n\n-- Migration 1657908958\nCOMMENT ON EXTENSION citext IS 'first privileged migration';\n\n-- Migration 1657908965\nCOMMENT ON EXTENSION citext IS 'second privileged migration';\n\nCOMMIT;\n"} -WARN migrations.runner runner/run.go:339 Adding migrating log for privileged migration, but not applying its changes {"schema": "frontend", "migrationID": 1657908958, "up": true} -WARN migrations.runner runner/run.go:339 Adding migrating log for privileged migration, but not applying its changes {"schema": "frontend", "migrationID": 1657908965, "up": true} -✅ Schema(s) are up-to-date! -```