<blockquote>
<p>How does craft know which migrations have been applied and which are new? I.e. Is it by comparing the craft_migrations table to the migration files found in '/vendor/craftcms/cms/src/migrations' folder (or plugin folders)?</p>
</blockquote>
<p>Exactly!</p>
<blockquote>
<p>Where does the information from running 'php craft migrate/new' and 'php craft migrate/history' come from?</p>
</blockquote>
<p><code>migrate/history</code> purely checks the <code>migrations</code> table in the database for a list of migrations that have already run.</p>
<p><code>migrate/new</code> grabs the same list of migrations from the database that <code>migrate/history</code> does, then compares it again the <code>migrations</code> folder on the file system to find any <em>newer</em> migrations (using the timestamp in the filename) that haven't run yet and returns that list.</p>
<blockquote>
<p>So clearly something is out of sync (or is terribly wrong in this project).</p>
</blockquote>
<p>Something does sound out-of-sync to me.</p>
<blockquote>
<p>How are version numbers and migrations associated with each other?</p>
</blockquote>
<p>Craft's (and a plugin's) version number is independent of migrations. Both have a separate concept called a <a href="https://docs.craftcms.com/api/v3/craft-base-plugintrait.html#schemaversion" rel="nofollow noreferrer">schemaVersion</a>, and when that number gets incremented, that tells Craft that a plugin (or itself) that there are new migrations that need to run.</p>
<blockquote>
<p>What determines the order that migrations are run?</p>
</blockquote>
<p>They are sorted, but since timestamps are embedded in the migration names, they will run from the oldest unapplied migrations to the newest unapplied migrations.</p>
<blockquote>
<p>Finally, if a migration fails, is there something else that should be done besides restoring the DB to reset the craft state, before attempting to run migrate/all again?</p>
</blockquote>
<p>Nope - restore from a pre-update attempt database back, fix whatever caused it to fail, then try again.</p>

CC BY-SA 4.0
2020-12-14T23:37:58.587Z
Thanks for the excellent answer! I suspected as much, but saw enough inconsistencies, that I was starting to question my assumptions. Great to know not insane ;)
Douglas McDonald
CC BY-SA 4.0
2020-12-14T19:20:12.657Z
2020-12-14T19:20:12.657Z
Brad Bell
<p>Can someone please help explain some basics regarding migrations and the associated CLI commands to help troubleshoot when things fail? Specifically,</p>
<p><strong>How does craft know which migrations have been applied and which are new?</strong>
I.e. Is it by comparing the <code>craft_migrations</code> table to the migration files found in '/vendor/craftcms/cms/src/migrations' folder (or plugin folders)?</p>
<p><strong>Where does the information from running 'php craft migrate/new' and 'php craft migrate/history' come from?</strong> I ask because, when running <code>php craft migrate/all</code> and a migration fails, if I reload the previous DB and run <code>migrate/new</code> it says &quot;No new migrations found&quot;, which is clearly wrong. Likewise running <code>migrate/history</code> displays &quot;No migration has been done before.&quot; But when running <code>migrate/all</code> again it does attempt to run the migrations again. So clearly something is out of sync (or is terribly wrong in this project).</p>
<p><strong>How are version numbers and migrations associated with each other?</strong> I.e. Is it simply based on whatever migration files happen to currently exist in the 'migrations' folder based on the last <code>composer update</code>?</p>
<p><strong>What determines the order that migrations are run?</strong> I.e. Are they simply run alphabetically, based on the file names in the 'migrations' folder?</p>
<p><strong>Finally, if a migration fails, is there something else that should be done besides restoring the DB to reset the craft state, before attempting to run <code>migrate/all</code> again?</strong></p>
<p>Appreciate the help. Thanks.</p>

<craft3><migration><cli>
Understanding migrations and CLI commands
# Understanding migrations and CLI commands

(Asked by: username_0 on 2020-12-13)

Can someone please help explain some basics regarding migrations and the associated CLI commands to help troubleshoot when things fail? Specifically,

**How does craft know which migrations have been applied and which are new?**
I.e. Is it by comparing the `craft_migrations` table to the migration files found in '/vendor/craftcms/cms/src/migrations' folder (or plugin folders)?

**Where does the information from running 'php craft migrate/new' and 'php craft migrate/history' come from?** I ask because, when running `php craft migrate/all` and a migration fails, if I reload the previous DB and run `migrate/new` it says "No new migrations found", which is clearly wrong. Likewise running `migrate/history` displays "No migration has been done before." But when running `migrate/all` again it does attempt to run the migrations again. So clearly something is out of sync (or is terribly wrong in this project).

**How are version numbers and migrations associated with each other?** I.e. Is it simply based on whatever migration files happen to currently exist in the 'migrations' folder based on the last `composer update`?

**What determines the order that migrations are run?** I.e. Are they simply run alphabetically, based on the file names in the 'migrations' folder?

**Finally, if a migration fails, is there something else that should be done besides restoring the DB to reset the craft state, before attempting to run `migrate/all` again?**

Appreciate the help. Thanks.

**Tags:** craft3, migration, cli


---

## 1 answers

### Answer by username_1 on 2020-12-14. Score: 2 | Accepted answer

> How does craft know which migrations have been applied and which are new? I.e. Is it by comparing the craft\_migrations table to the migration files found in '/vendor/craftcms/cms/src/migrations' folder (or plugin folders)?

Exactly!

> Where does the information from running 'php craft migrate/new' and 'php craft migrate/history' come from?

`migrate/history` purely checks the `migrations` table in the database for a list of migrations that have already run.

`migrate/new` grabs the same list of migrations from the database that `migrate/history` does, then compares it again the `migrations` folder on the file system to find any *newer* migrations (using the timestamp in the filename) that haven't run yet and returns that list.

> So clearly something is out of sync (or is terribly wrong in this project).

Something does sound out-of-sync to me.

> How are version numbers and migrations associated with each other?

Craft's (and a plugin's) version number is independent of migrations. Both have a separate concept called a [schemaVersion](https://docs.craftcms.com/api/v3/craft-base-plugintrait.html#schemaversion), and when that number gets incremented, that tells Craft that a plugin (or itself) that there are new migrations that need to run.

> What determines the order that migrations are run?

They are sorted, but since timestamps are embedded in the migration names, they will run from the oldest unapplied migrations to the newest unapplied migrations.

> Finally, if a migration fails, is there something else that should be done besides restoring the DB to reset the craft state, before attempting to run migrate/all again?

Nope - restore from a pre-update attempt database back, fix whatever caused it to fail, then try again.

> **Comments:**
> **username_0**: Thanks for the excellent answer! I suspected as much, but saw enough inconsistencies, that I was starting to question my assumptions. Great to know not insane ;)  

---

