PHPackages                             dbmigrate/dbmigrate - 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. dbmigrate/dbmigrate

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

dbmigrate/dbmigrate
===================

A Database Migration Tool Similar to Flyway

v2.0.0(8y ago)315.5k↓82%1[2 PRs](https://github.com/newcron/dbmigration/pulls)MITPHPPHP >=5.3.0CI failing

Since Jan 3Pushed 3y agoCompare

[ Source](https://github.com/newcron/dbmigration)[ Packagist](https://packagist.org/packages/dbmigrate/dbmigrate)[ RSS](/packages/dbmigrate-dbmigrate/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (3)Dependencies (2)Versions (4)Used By (0)

dbmigrate - Database Migration Tool
===================================

[](#dbmigrate---database-migration-tool)

dbmigrate is a simple utility to automate changes to your database (schema and contents). This tool is typically helpful for automating code deployments or in scenarios, where it is necessary to audit database changes. It's an alternative to tools like [Doctrine Migrations](http://doctrine-orm.readthedocs.io/projects/doctrine-migrations/en/latest/reference/generating_migrations.html)that focus on automatically keeping a database in sync with the domain model. If you want to keep the database schema in your hands and like the simplicity of versioned SQL files, then this tool might be just right for you.

dbmigrate is heavily inspired from [Flyway](http://flywaydb.org/).

dbmigrate currently supports these database engines:

- MySQL
- PostgreSQL

### How does it work

[](#how-does-it-work)

All your migration SQL files will be stored in one directory (let's call it the *migrations directory*). There is no rule for the filename, dbmigrate will find anything ending with *.sql*.

The first thing you will need to do is to run dbmigrate's *initialization* command, which will create a table *installed\_migrations* in your db:

FieldTypeidint(10) unsignedinstallation\_timetimestampmigration\_file\_namevarchar(255)migration\_file\_checksumvarchar(32)successenum('true','false')Once done, every time you run the *migrate* task, it will scan the migrations directory for migrations that are not yet logged in the *installed\_migrations* table, execute them and store success/failure inside that table.

There are some more things regarding the installation:

1. If dbmigrate finds *several* SQL files that are not installed, it will sort them [naturally using natsort](http://php.net/manual/de/function.natsort.php) before running them.
2. If running a migrations results in an SQL error, the result will be stored with *success=false*. Dbmigrate will not allow to run any migration if an unsuccessful migration is found in database. (see the notes on resolving errors below).
3. Besides the filename, dbmigrate also stores the checksum of the files content. It will fail if it detects that an already installed migration file has been altered after installation. (see the notes on resolving errors below).

### Usage

[](#usage)

This is a code-only tool, meaning that there is no CLI/Web interface. You operate the tool using PHP code. It works on top of *PDO*, meaning that you will need to pass it a preconfigured *PDO* instance pointing to your database.

##### Initializing (first time only)

[](#initializing-first-time-only)

The framework depends on the existence of a *journal* table in your Database, being named *installed\_migrations*. The first time you run the migration tool, you'll need to *Initialize* it (generating that schema).

```
$pdo = new PDO("mysql:host=yourdbhost;database=yourdb", "youruser", "yourpass");

call_user_func(new \dbmigrate\Initialize($pdo));
```

##### Running Migrations (on every deployment)

[](#running-migrations-on-every-deployment)

All your DB migrations (which are basically *.sql* Files) will need to be stored in one directory. When you point dbmigrate to this directory, it will compare all *.sql* files in there with the data from the *installed\_migrations* table and install migrations that are not yet installed.

To determine if a migration has been installed or not, the dbmigrate will compare the filenames (case sensitive!). If multiple migrations have to be installed at once, the order in which they are installed will be the natural order of the filenames (using [natsort](http://php.net/natsort)).

```
$pdo = new PDO("mysql:host=yourdbhost;database=yourdb", "youruser", "yourpass");

call_user_func(new \dbmigrate\Migrate($pdo, new \SplFileInfo("/path/to/your/sql/folder")));
```

All the sql files in the "/path/to/your/sql/folder" directory will be read and run against the database. Each file will be run inside a single transaction, if anything within that file fails then all commands in that file will be rolled back.

##### Dry-Running Migrations

[](#dry-running-migrations)

If you just want to know if your new migration *would* be going to be installed, you can perform a dry run. It will not alter your database in any way, but it will tell you which migrations were going to be installed, if you would run a migration now.

To perform a Dry-Run:

```
$pdo = new PDO("mysql:host=yourdbhost;database=yourdb", "youruser", "yourpass");

$installedMigrations = call_user_func(new \dbmigrate\MigrateDryRun($pdo, new \SplFileInfo("/path/to/your/sql/folder")));

var_dump($installedMigrations);
```

### Resolving Errors

[](#resolving-errors)

When doing migrations, there are two things in which dbmigrate purposely breaks. In both cases it's very likely that the database is out of sync with the migration files and needs to be manually checked:

1. a migration could not be installed successfully
2. migration file was altered after installation

##### Migration could not be installed successfully

[](#migration-could-not-be-installed-successfully)

MySQL [does not support transactions over alter tables](http://dev.mysql.com/doc/refman/5.7/en/cannot-roll-back.html) - so if a migration contains a syntax error, there is no way to roll back (imagine, you've got several alter table statements in your SQL file, the first one passes, the second one as a syntax error and is therefore ignored)

In these cases, all that dbmigrate knows, is that the DB is *not* in the expected state and therefore will not proceed doing any further migrations to the database - now and in the future.

To resolve that situation, you'll need to manually review the database and either

- Bring it back into the old state and delete the failed entry from the *installed\_migrations* table.
- Finish the migration manually and update the *installed\_migrations* record to be *success=true*.

##### Migration File was altered after Installation

[](#migration-file-was-altered-after-installation)

When a migration is installed, dbmigrate will store the checksum of the file at the time of installation. If that file is modified afterwards, dbmigrate will notify this and refus to do any new migration. Like above the reason for this is that it's unclear if the DB is in a valid state or not.

There are two ways to resolve that situation:

- Revert the old migration file so that the checksum is the same again
- Review the migration file and the state of the database - if there's no difference, just update the record in *installed\_migrations* to the new checksum.

### Extending/Running Tests

[](#extendingrunning-tests)

There is a set of Unit and Integration Tests ensuring the basic functionality of dbmigrate stays intact. To run them you will need

- Linux/MacOS
- Docker 1.8 or higher
- PHP 5.6 or higher

Running the tests is just a matter of

```
composer install
make tests
```

**Note For Linux Users:** Docker works a bit different on MacOS than on Linux. This is important to know as the IP address of Docker containers on Mac is dynamic, where it is always 127.0.0.1 on Linux. To have the Makefile work on Linux, just change the occurences of `docker-machine ip default` to `127.0.0.1`

###  Health Score

33

—

LowBetter than 74% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity30

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 66.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~358 days

Total

3

Last Release

3061d ago

Major Versions

v1.1.0 → v2.0.02017-12-21

### Community

Maintainers

![](https://www.gravatar.com/avatar/cabaa16ae7245296f81905fb5db23c2929f3667479443c259c21edf434d63298?d=identicon)[newcron](/maintainers/newcron)

---

Top Contributors

[![newcron](https://avatars.githubusercontent.com/u/1669950?v=4)](https://github.com/newcron "newcron (12 commits)")[![emmetog](https://avatars.githubusercontent.com/u/1182891?v=4)](https://github.com/emmetog "emmetog (6 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/dbmigrate-dbmigrate/health.svg)

```
[![Health](https://phpackages.com/badges/dbmigrate-dbmigrate/health.svg)](https://phpackages.com/packages/dbmigrate-dbmigrate)
```

###  Alternatives

[doctrine/orm

Object-Relational-Mapper for PHP

10.2k285.3M6.2k](/packages/doctrine-orm)[jdorn/sql-formatter

a PHP SQL highlighting library

3.9k115.1M102](/packages/jdorn-sql-formatter)[illuminate/database

The Illuminate Database package.

2.8k52.4M9.3k](/packages/illuminate-database)[mongodb/mongodb

MongoDB driver library

1.6k64.0M541](/packages/mongodb-mongodb)[ramsey/uuid-doctrine

Use ramsey/uuid as a Doctrine field type.

90340.3M208](/packages/ramsey-uuid-doctrine)[reliese/laravel

Reliese Components for Laravel Framework code generation.

1.7k3.4M16](/packages/reliese-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)