PHPackages                             patricknelson/silverstripe-migrations - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. patricknelson/silverstripe-migrations

ActiveSilverstripe-module[Database & ORM](/categories/database)

patricknelson/silverstripe-migrations
=====================================

SilverStripe Database Migration module. Facilitates atomic database migrations in SilverStripe 3.x

v0.3.6(4y ago)2026.7k6[12 issues](https://github.com/patricknelson/silverstripe-migrations/issues)[1 PRs](https://github.com/patricknelson/silverstripe-migrations/pulls)MITPHP

Since Apr 24Pushed 4y ago4 watchersCompare

[ Source](https://github.com/patricknelson/silverstripe-migrations)[ Packagist](https://packagist.org/packages/patricknelson/silverstripe-migrations)[ Docs](https://github.com/patricknelson/silverstripe-migrations)[ RSS](/packages/patricknelson-silverstripe-migrations/feed)WikiDiscussions master Synced 3w ago

READMEChangelogDependencies (2)Versions (13)Used By (0)

SilverStripe 3.x Database Migrations
====================================

[](#silverstripe-3x-database-migrations)

Facilitates atomic database migrations in SilverStripe 3.x. Inspired by [Laravel's migration capability](http://laravel.com/docs/master/migrations), this relatively simple module was built to work as an augmentation to the existing `dev/build` that is already commonplace in SilverStripe.

SilverStripe's database schema is *declarative*, which means that the code defines what the state of the database *currently should be* and therefore the system will do what it needs to do in order to change the current schema to match that declared structure at any given moment (by proxy of `dev/build`). In contrast, database migrations offer a method to *imperatively* define how that structure (as well as the data) should change progressively over time. The advantage to this is that it makes it easier for you to rename columns (while retaining data), combine multiple columns or even change the format of data over time without leaving behind legacy code which should no longer exist, helping keep things tidy.

Installation
------------

[](#installation)

### Composer

[](#composer)

1. Run `composer require "patricknelson/silverstripe-migrations:dev-master"`
2. Run `sake dev/build` from the command line to ensure it is properly loaded into SilverStripe.

### Manual Installation

[](#manual-installation)

1. Download the latest [repository zip file](https://github.com/patricknelson/silverstripe-migrations/archive/master.zip).
2. Extract the folder `silverstripe-migrations-master` and rename it `migrations`.
3. Copy that folder to the root of your website.
4. Run `sake dev/build` from the command line to ensure it is properly loaded into SilverStripe.

How to Use
----------

[](#how-to-use)

This module sets up a task called `MigrateTask` which is available from the command line only via either:

- `sake dev/tasks/MigrateTask [option]`
- `php framework/cli-script.php dev/tasks/MigrateTask [option]`

Using this task, you can do the following:

1. Run migrations (i.e. "up").
    - `sake dev/tasks/MigrateTask up`
2. Reverse previous migrations (i.e. "down").
    - `sake dev/tasks/MigrateTask down`
3. Make a new migration file for you with boilerplate code.
    - `sake dev/tasks/MigrateTask make:migration_name`
    - **Note:** This file will be automatically placed in your project directory in the path `/code/migrations`. You can customize this location by defining a `MIGRATIONS_PATH` constant which should be the absolute path to the desired directory (either in your `_ss_environment.php` or `_config.php` files). Also, migration files that are automatically generated will be pseudo-namespaced with a `Migration_` prefix to help reduce possible class name collisions.

### How it Works

[](#how-it-works)

**Up**

Each time you run an `up` migration, this task will look through all migration files that have been setup in your `/code/migrations` folder (which you can customize) and then compare that to a list of migrations that it has already run in the `DatabaseMigrations` table. If it finds a new migration that has not yet been run, it will execute the `->up()` method on that migration file and keep a record of it in that table. Also, it will make sure to only run migrations in alphanumeric order based on their file name.

**Down**

When multiple migrations are run together, they are considered a single batch and can be rolled back (or reversed) all together as well by using the `down` option. When `down` migrations are performed, they are done in reverse order one batch at a time to help ensure consistency.

### Writing Migrations

[](#writing-migrations)

You can easily generate migration files by running the task with the `make:migration_name` option (switching out `migration_name` with a concise description of your migration using only underscores, letters and numbers).

**Example:**

`sake dev/tasks/MigrateTask make:change_serialize_to_json`

This will generate a file following the format `YYYY_MM_DD_HHMMSS_change_serialize_to_json.php`, using the current date to name the file (to ensure it is executed in order) and containing the class `Migration_ChangeSerializeToJson`. It should look like this:

```