Skip to content

A platform for community discussion. Free, open, simple.

DEV: Update discourse-migration skill (#44849)

David Taylor80c069514c71
diff --git a/.skills/discourse-migration/SKILL.md b/.skills/discourse-migration/SKILL.md
index 2908c5835e1..9931ee48ecf 100644
--- a/.skills/discourse-migration/SKILL.md
+++ b/.skills/discourse-migration/SKILL.md
@@ -14,6 +14,23 @@ Plugins mirror this: `plugins/<name>/db/migrate/` and `plugins/<name>/db/post_mi
SafeMigrate is a dev/test guard only (disabled in production).
+## Deploy order
+
+A zero-downtime deploy, like the `/admin/upgrade` upgrader, runs in this order:
+
+1. Pre-deploy migrations (with `SKIP_POST_DEPLOYMENT_MIGRATIONS=1`), then seeds. The old code is still running.
+2. The new code starts.
+3. The old code stops.
+4. Post-deploy migrations.
+
+A plain `bin/rake db:migrate` runs both kinds together, sorted by version, and seeds at the end. Migrations have to work either way.
+
+If the new code or its seeds need some data at boot, change it in a pre-deploy migration. The app reads site settings when it starts and doesn't notice when a migration changes them later, so a setting renamed post-deploy reads as its default until the next restart. Seeds that find rows by the new name, like `BadgeGrouping.seed(:name)`, create a duplicate before a post-deploy rename gets to run.
+
+A pre-deploy migration can't depend on a post-deploy one. All pending pre-deploy migrations run first, whatever their timestamps. If you need an older post-deploy migration to run first, promote it.
+
+The old code keeps reading and writing the old data until it stops.
+
## Generating migrations
Always use generators — never hand-write timestamps. Manual timestamps like `120000`/`120001` cause collisions.
@@ -120,6 +137,30 @@ Same pattern via `lib/migration/table_dropper.rb`:
If table is already fully unused, just `drop_table` directly in a post-deploy migration.
+## Renaming tables
+
+When the new code needs the new table name at boot, for example after a plugin rename:
+
+1. In a pre-deploy migration, rename the table and add a view with the old name so the old code keeps working. `rename_table` handles the primary key, the id sequence and conventionally named indexes. Rename any other indexes, constraints, triggers and trigger functions yourself.
+
+ ```ruby
+ def up
+ Migration::SafeMigrate.disable!
+ rename_table :old_things, :new_things
+ execute "CREATE VIEW old_things AS SELECT * FROM new_things"
+ ensure
+ Migration::SafeMigrate.enable!
+ end
+ ```
+
+2. In a post-deploy migration, drop the view with `DROP VIEW IF EXISTS old_things`. This fails if `old_things` is still a table.
+
+Give the view the old name, not the new one, so later pre-deploy migrations can still alter the real table. The old code can only write through the view because production loads the schema cache before forking (`Discourse.preload_rails!`). A process that reads the view's schema fresh sees no primary key and no column defaults.
+
+In the same pre-deploy migration, rename the data that refers to the old names: site settings with their `site_setting_groups` and `site_setting_localizations` rows, STI `type` and polymorphic `*_type` columns, custom field names, and `plugin_store_rows.plugin_name`. The old code can still write rows with the old names before it stops, so run the same updates again in the post-deploy migration. Guard each one with `NOT EXISTS` so it can't hit a unique index.
+
+`RenameVoiceToLive` and `FinishRenameVoiceToLive` in `plugins/live` do all of this.
+
## Removing site settings
The most common migration type. Use `execute` with `DELETE` or `UPDATE`:
@@ -132,7 +173,13 @@ execute "DELETE FROM site_settings WHERE name = 'old_setting_name'"
execute "UPDATE site_settings SET name = 'new_name' WHERE name = 'old_name'"
```
-Always `up`/`down` with `raise ActiveRecord::IrreversibleMigration`.
+Always `up`/`down` with `raise ActiveRecord::IrreversibleMigration`. Rename settings in a pre-deploy migration so the new code starts with the right value.
+
+## Promoting post-deploy migrations
+
+After each ESR release, `script/promote_migrations` moves post-deploy migrations from before that release into `db/migrate/`. You can promote one early when a new pre-deploy migration depends on it. Move it with `git mv` and keep the filename. Sites that already ran it won't run it again, since the version doesn't change.
+
+SafeMigrate checks pre-deploy migrations that are newer than the oldest core post-deploy migration (`Migration::SafeMigrate.earliest_post_deploy_version`). That includes CI's clean migrate in `db:check_structure_dump`. So if an early-promoted migration drops a foreign key or a column, or renames a table, wrap it in `Migration::SafeMigrate.disable!` and `ensure Migration::SafeMigrate.enable!`.
## Indexing
@@ -308,3 +355,5 @@ Both tasks spin up a disposable database and load all bundled plugins, so output
13. No rows inserted on fresh installs — seed data lives in `db/fixtures/`; inserts that exist only to preserve behavior on upgrades are gated on `Migration::Helpers.existing_site?`
14. After schema-altering migrations, `bin/rake db:dump_structure` and `bin/rake annotate:clean` were run and the regenerated files committed
15. Transaction-disabled migrations (`disable_ddl_transaction!`) contain only the operation that requires it (concurrent index or batched backfill), no other schema changes
+16. Data the new code or its seeds need at boot is changed pre-deploy, and renamed tables get a view with the old name
+17. Pre-deploy migrations don't depend on post-deploy ones (promote those early if needed)