<p>The object of migrations is to provide a way for existing installations of your plugin to get the updated db schema as you update your plugin, without having to uninstall (which would mean they would lose all plugin data) and then reinstall your plugin.</p>

<blockquote>
  <p>If your schema changes over the life of your plugin, you can write a migration to keep existing installations updated with the latest schema. Craft automatically checks for new migrations whenever a plugin’s version number changes.</p>
</blockquote>

<p><a href="https://craftcms.com/docs/plugins/migrations" rel="nofollow noreferrer">https://craftcms.com/docs/plugins/migrations</a></p>

<p>This is because when a plugin is installed, Craft/Yii will go through your records and create the needed tables/columns as you have defined.</p>

<p>If a user downloads the updated plugin and replaces the current version, they won't have the new columns and things could break as they navigate and try to add data.</p>

<p>This is where migrations play an important role, they are to prevent existing users having to lose all plugin data by uninstalling and reinstalling, so when you change your plugin version, Craft will see there is an update and run through all the migrations to bring them up to the current version.</p>

<p>This is especially handy if for example someone has version <code>0.1.0</code> and they update to version <code>1.0.0</code>, which could be quite a leap.</p>

<p>So in short, if you add new attributes to your plugin record, they will be added for <strong>new installations</strong> but migrations are only for <strong>existing installations</strong></p>

CC BY-SA 3.0
2015-08-20T16:51:50.863Z
+1 "migrations are only for existing installations" ... Craft keeps a complete log of every migration it's ever run (core & plugins), so no migration will ever be run twice. When a brand new plugin is installed, all of its existing migrations will be logged (but not run) immediately, to keep in sync with any future updates.
Lindsey D
CC BY-SA 3.0
2015-08-20T16:37:18.357Z
2017-11-29T10:20:07.240Z
2017-11-29T10:20:07.240Z
Alec Ritson
<p>I'm developing a plugin, bumping the version number to run the migrations I'm creating but then, for sanity, checked they run when the plugin is installed for the first time, which doesn't seem to be the case.</p>

<p>Could someone clarify how to get the migrations to run on install? </p>

<plugin-development><migration>
Does a plugin runs it's migrations on install?
# Does a plugin runs it's migrations on install?

(Asked by: username_0 on 2015-08-20)

I'm developing a plugin, bumping the version number to run the migrations I'm creating but then, for sanity, checked they run when the plugin is installed for the first time, which doesn't seem to be the case.

Could someone clarify how to get the migrations to run on install?

**Tags:** plugin-development, migration


---

## 1 answers

### Answer by username_1 on 2015-08-20. Score: 7 | Accepted answer

The object of migrations is to provide a way for existing installations of your plugin to get the updated db schema as you update your plugin, without having to uninstall (which would mean they would lose all plugin data) and then reinstall your plugin.

> If your schema changes over the life of your plugin, you can write a migration to keep existing installations updated with the latest schema. Craft automatically checks for new migrations whenever a plugin’s version number changes.

<https://craftcms.com/docs/plugins/migrations>

This is because when a plugin is installed, Craft/Yii will go through your records and create the needed tables/columns as you have defined.

If a user downloads the updated plugin and replaces the current version, they won't have the new columns and things could break as they navigate and try to add data.

This is where migrations play an important role, they are to prevent existing users having to lose all plugin data by uninstalling and reinstalling, so when you change your plugin version, Craft will see there is an update and run through all the migrations to bring them up to the current version.

This is especially handy if for example someone has version `0.1.0` and they update to version `1.0.0`, which could be quite a leap.

So in short, if you add new attributes to your plugin record, they will be added for **new installations** but migrations are only for **existing installations**

> **Comments:**
> **username_2**: +1 "migrations are only for existing installations" ... Craft keeps a complete log of every migration it's ever run (core & plugins), so no migration will ever be run twice. When a brand new plugin is installed, all of its existing migrations will be logged (but not run) immediately, to keep in sync with any future updates.  

---

