Refactor plugin migrations into structure and patches

Use it to turn a long list of migration scripts into one structure file per table plus versioned patches, without changing the schema on new or existing installs.

  • Tested with Opus 5.5
  • October CMS 4.x
  • Database
  • By the October CMS team
  • Added on Nov 21, 2026
Prompt
You are helping me clean up the migrations of a plugin for October CMS 4, which runs on Laravel. Plugin: [Author.Plugin, eg: Acme.Library] Installed on live sites: [yes or no] Next version: [eg: 2.1.0, or none] Reorganise the scripts in the plugin's updates folder into structure files and patches. The tables must come out exactly as they are today, on a new install and on a site that upgrades from any earlier version. A structure file creates one table as it stands today, with every column that later scripts added or changed. The files are numbered in the order the tables were first created and named without the plugin prefix, eg: 000001_create_books.php, 000002_create_authors.php. ```php <?php use October\Rain\Database\Schema\Blueprint; use October\Rain\Database\Updates\Migration; return new class extends Migration { public function up() { Schema::create('acme_library_books', function (Blueprint $table) { $table->increments('id'); $table->string('title')->nullable(); $table->timestamps(); }); } public function down() { Schema::dropIfExists('acme_library_books'); } }; ``` A patch changes tables that already exist. It is named after the plugin version that ships it, eg: migrate_v2_1_0.php, and is the same kind of class. Its up() checks before each change with Schema::hasTable or Schema::hasColumn, so it is safe on any install and safe to run twice. Its down() is empty. 1. Read version.yaml and every script it lists, in version order. Work out the final state of each table: every column with its type, length, nullable, default and indexes, including index names that were set by hand. 2. Write the structure files from that. Change nothing about a column: keep increments as increments, keep types, lengths and defaults that look wrong, and add no foreign keys. Only the order of the columns may be tidied, with the timestamps last. Leave out the namespace and any engine line. 3. Rewrite version.yaml. List each structure file under the version that first created its table, in the place of the script it replaces. Keep every version and its description, without the other scripts that the structure files replace. A version with only a description goes on one line, eg: v1.0.2: Added a status column. Write version numbers with a v, eg: v1.0.1. 4. Delete the scripts that the structure files replace. Keep seed scripts and any script that changes data, in the version where it is, and tell me about each one. 5. If a next version is given, add it to version.yaml with a line that says what the release does. If the plugin is installed on live sites, add one patch for the next version and list it in version.yaml under that version. The patch repeats every change the deleted scripts made to a table after creating it, each behind its own check, so a site on any earlier version ends with the final tables. It creates a missing table by running its structure file: App::make('db.updater')->setUp(__DIR__.'/000002_create_authors.php'). It repeats a change of column type with ->change() and every attribute the column has. If it is not installed on live sites, add no patch. Check your work at the end. Write out each table's columns from the new structure files and compare them with the list from step 1. Show me both lists, any difference, and anything in the old scripts you could not carry over. Do not change the schema, even to fix a mistake, list what looks wrong instead. Do not edit models or other code, and do not run migrations or write to the database yourself. Finish with the commands I need to run, and suggest nothing that rolls back, refreshes or removes the plugin.
How to use

Fill in the plugin code, eg: Acme.Library, then paste it into an AI assistant that can edit the files in your project. Commit your work first, so the cleanup is one change you can review and undo.

Answer yes to installed on live sites when any site has the plugin and will upgrade to this release. Give the next version as a minor or major release, eg: 2.1.0, since it ships a database patch. Answer no for a plugin still in development. The next version is optional then: give one to record the cleanup as a release, or leave it as none.

The result has two kinds of file in the updates folder:

  • Structure is one numbered file for each table, holding the whole table. A new install gets its tables from these.
  • Patches are named after a release, eg: migrate_v2_1_0.php, and bring existing installs up to date. Each change checks first, so a patch does nothing on a new install.

From then on, a schema change goes in both places: in the table's structure file for new installs, and in a patch for the sites that already have the table.

Check these in the result:

  • Every table has one numbered file, and its up() holds every column the old scripts added.
  • The two column lists the assistant shows are the same. Nothing about a column changed, only the order.
  • version.yaml still has every version and its description, plus the next version if you gave one. Only the script lines are gone, and a version with no scripts sits on one line.
  • On a new install, php artisan october:migrate creates the tables, and running it again changes nothing.

With live sites, try the release on a copy of a live database first. php artisan october:migrate applies the patch without errors, and the tables match a new install.

Good follow-up prompts:

  • "Add a [column] column to [table]. Put it in the table's structure file and in a patch for version [version]."
  • "Write a test that builds the tables from the structure files and compares every column and index with this list."
  • "Fix [item] from the list of what looks wrong. If the plugin is not on live sites, change only its structure file. Otherwise also add it to the patch for [version]."

Was this prompt helpful?

Still need help?
October Forum

Community members share experiences, ask questions and exchange tips.

Discord

Talk with other October CMS developers in real time.

Custom Development

Hire the October CMS team to work on your website.

Contact Us

For bug reports and help with this website. See the roadmap or submit an idea on the Portal.