PHPackages                             phpixie/migrate - 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. phpixie/migrate

ActiveLibrary[Database & ORM](/categories/database)

phpixie/migrate
===============

PHPixie migrations component

3.7.2(5y ago)1116.8k6[1 PRs](https://github.com/PHPixie/Migrate/pulls)2BSD-3-ClausePHP

Since Jun 4Pushed 5y ago1 watchersCompare

[ Source](https://github.com/PHPixie/Migrate)[ Packagist](https://packagist.org/packages/phpixie/migrate)[ Docs](http://phpixie.com)[ RSS](/packages/phpixie-migrate/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (4)Dependencies (4)Versions (17)Used By (2)

Migrate
=======

[](#migrate)

PHPixie migration library

[![Author](https://camo.githubusercontent.com/24a0a94bb83eb81ba03c32074967dc730174cfd2849e984169db461d955cdbb9/687474703a2f2f696d672e736869656c64732e696f2f62616467652f617574686f722d40647261636f6e792d626c75652e7376673f7374796c653d666c61742d737175617265)](https://twitter.com/dracony)[![Source Code](https://camo.githubusercontent.com/5093ade3d2e3babe64fde288a482a8b48dd90bb8a843544ed7b82aeec147a624/687474703a2f2f696d672e736869656c64732e696f2f62616467652f736f757263652d706870697869652f6d6967726174652d626c75652e7376673f7374796c653d666c61742d737175617265)](https://github.com/phpixie/migrate)[![Software License](https://camo.githubusercontent.com/b60331a2084501dc07cf6d6964c0da58dd005d89c45cf3b28b4b22b60f5ec00f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4253442d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://github.com/phpixie/orm/blob/master/LICENSE)

PHPixie Migrate allows you to version your database schema and apply updates to it in a conistent way. It also allows you to define some data to be inserted in the database, which is useful when writing tests or demo-ing the code.

### Configuration

[](#configuration)

Let's look at the default configuration in `assets/config/migrate.php`:

```
return array(
    // migration configs
    'migrations' => array(
        'default' => array(

            // database connection name
            'connection' => 'default',

            // migration files path, relative to /assets/migrate/
            'path'       => 'migrations',

            // optional:

            // name of the table to keep version data it
            'migrationTable' => '__migrate',

            // name of the version field in the migration table
            'lastMigrationField' => 'lastMigration'
        )
    ),

    // seed data configs (we'll cover it later)
    'seeds' => array(
        'default' => array(

            // database connection name
            'connection' => 'default',

            // seed files path, relative to /assets/migrate
            'path' => 'seeds'
        )
    )
);
```

Most proably you won't need to change anything here, unless you are handling multiple databases, or different sets of seed data.

### Creating and destroying the database

[](#creating-and-destroying-the-database)

You can now create and destroy your database using the command line. This is done using the `framework:database` command:

```
framework:database ACTION [ CONFIG ]
Create or drop a database

Arguments:
ACTION    Either 'create' or 'drop'
CONFIG    Migration configuration name, defaults to 'default'
```

E.g. running `conole framework:database create` will create a database.

### Migrations

[](#migrations)

First let's start with a brief introduction. Migrations allow you to keep your database schema modifications in your code, which is much more convenient than sharing database dumps or manually applying changes on your production database. They work in simple way: a special table is created in the database that has a single row and column and keeps the name of the last applied migration. When a migration is executed all migrations that have a name "larger" than the current one will be applied in `natsort()` order. E.g. if we have files 1.sql, 2.sql,...22.sql and the latest executed migration is 13.sql then all migrations between 14 and 22 will be executed and the last migration field will be set to 22. The migrations can be written in .sql and .php formats.

### SQL migrations

[](#sql-migrations)

These are very simple. It is just an SQL file with statememnts delimited by the `-- statement` separator:

```
CREATE TABLE fairies(
    id int NOT NULL,
    name VARCHAR(255)
);

-- statement

CREATE TABLE flowers(
    id int NOT NULL,
    name VARCHAR(255)
);
```

### PHP migrations

[](#php-migrations)

These are just PHP files that also allow you to execute SQL commands and also provide access to the Database component.

```
$this->execute("CREATE TABLE fairies(
    id int NOT NULL,
    name VARCHAR(255)
)");

$this->message("Output some message to the console");

// Usual Database queries
$this->connection()->updateQuery()
    ->table('users')
    ->set(['role' => 'user'])
    ->execute();
```

PHP migrations allow you a bit more flexibility than SQL ones, but SQL migration files can also be executed directly on the database without even using the Migrate component.

It is highly recommended to add some short description to your migration names, and since we are using `natsort()` order you can safely write any comment you like after for example an underscore: `33_fairies_table.sql`.

You can also use subfolders in your migrations directory, which is helpful if you have a lot of files there. In that case the sorting will be applied to the entire subpath, not just the file name. E.g. you can have your files in such structure: `/2016/03/22/fairies_table.sql`.

To execute the migrations use the `framework:migrate` command:

```
framework:migrate [ CONFIG ]
Run migrations on the database

Arguments:
CONFIG    Migration configuration name, defaults to 'default'
```

We also need to address some questions here.

*Why arent there down migrations for rollback?*

If you think from the perspective of the database itself, there is no such thing as a schema rollback. Rolling back is just applying another migration that reverses previous changes. In many cases a rollback is not even possible, for example if you rollback table deletion, the rollback might recreate the table structure but won't bring back the data in it.

*Why are changes written in raw SQL and not using some universal methods like `createTable` etc.?*

The problem of universal methods is that they often omit the subtle differences between databases and make too many assumptions. There is also the possibility that after an update such universal library might start creating the tables in a slightly different fashion and then your production database that had the migrations applied months ago will be in a different state than a new database whre the same migrations have been applied more recently. Additionaly there already exist many tools for creating and converting database schemas that there is no need to replicate this functionality in a migration library.

### Seeds

[](#seeds)

Seeds are sets of data that can be used to fill the database. This can be some default users, item categories etc. They also can be used to prepare your application for some functional tests. Each seed file contains data for a single table and it's name must match the name of that table. The files themselves can be either *.json* or *.php*, e.g:

```
// /assets/migrate/seeds/fairies.php