PHPackages                             tinyapps/db-updater - 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. tinyapps/db-updater

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

tinyapps/db-updater
===================

Simple PHP library for managing and executing database updates.

v1.0.11(4y ago)2294[2 issues](https://github.com/tinyappsde/db-updater/issues)MITPHPPHP ^7.4.0 || ^8.0

Since Mar 16Pushed 4y ago1 watchersCompare

[ Source](https://github.com/tinyappsde/db-updater)[ Packagist](https://packagist.org/packages/tinyapps/db-updater)[ RSS](/packages/tinyapps-db-updater/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (6)Dependencies (1)Versions (11)Used By (0)

[![Unit Tests](https://github.com/tinyappsde/db-updater/actions/workflows/unit-test.yml/badge.svg?branch=master)](https://github.com/tinyappsde/db-updater/actions/workflows/unit-test.yml)

Database Updater
================

[](#database-updater)

This is a simple PHP library for managing and executing database updates. It allows you to store database updates in a directory or a single config file and easily execute them in different environments.

Each update needs a unique id. Unlike an incremental versioning this makes it possible to have independent updates (e.g. from different features and development branches) that can be automatically executed once the feature is merged or deployed.

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

[](#installation)

`composer require tinyapps/db-updater`

The following modes are supported: *Directory*, *JSON Config* and *PHP Config*. You'll find examples for each in the examples folder.

In JSON/PHP modes an empty config file will be created if no file exists at the given file path. Alternatively you'll find configs in the examples folder.

Getting Started
---------------

[](#getting-started)

After following the installation instructions above, you’ll need to decide which config mode to use. The directory mode, where each update is stored in a dedicated file in an updates folder, is enabled by default. Alternatively you can use the single config mode with a JSON or PHP file.

### Pick your config mode

[](#pick-your-config-mode)

- Directory Mode
    - Create an empty folder where you will store the updates in – e.g. `db/updates/` . You’ll need to pass this directory to the updater later.
- JSON/PHP Config Mode
    - When initializing the updater for the first time, the config is automatically generated at your given path. Make sure this path points to a writable folder and no file with that name exists. You’ll need to pass the ` Updater::MODE_JSON` or `Updater::MODE_PHP` as the third argument for the updater’s constructor ( `new Updater(...)`) to enable the mode.

### Execute Updates

[](#execute-updates)

- Create a script file that runs outstanding updates. In this example we’ll create a new PHP file here: `scripts/db-updates.php`.
- At first you’ll need a PDO instance for your database connection. In case you don’t have a helper class or similar that returns the PDO instance in your project just yet, please read this documentation: [PHP: PDO::\_\_construct - Manual](https://www.php.net/manual/pdo.construct.php)
- Create a new updater instance with your PDO connection in your script using `$updater = new Updater($pdo, __DIR__ . '/../db/updates');`
    - If using the JSON/PHP mode you’ll need to pass the third argument
- Run outstanding updates (with output) using `$updater->executeOutstandingUpdates(false);` (see more details in the examples below)

### Save a new update

[](#save-a-new-update)

There are two options for adding an update:

- Programmatically create an update by using the `saveNewUpdate` method of the updater. (see example below)
- Manually create a file containing the update queries. The file name is used as the ID of the update and is inevitably unique in the directory mode. E.g. create a file `my-first-update.sql` in your updates folder and put your queries in there (separated by a semicolon `;` ).

Example Code
------------

[](#example-code)

### Initialization

[](#initialization)

```
use TinyApps\DbUpdater\Updater;

$pdo = new PDO(...); // Your PDO instance
$updater = new Updater($pdo, __DIR__ . '/path/to/updates', Updater::MODE_DIR);
```

### Execute outstanding updates

[](#execute-outstanding-updates)

```
use TinyApps\DbUpdater\Exceptions\UpdateFailureException;

try {
	$executedUpdates = $updater->executeOutstandingUpdates();
	echo count($executedUpdates) . ' outstanding updates were executed';
} catch (UpdateFailureException $e) {
	// An update failed
	echo $e->getMessage();
}
```

### Execute a single update

[](#execute-a-single-update)

```
use TinyApps\DbUpdater\Exceptions\UpdateFailureException;

try {
	$updater->executeUpdateWithId('example-update');
	echo 'Update #example-update executed';
} catch (UpdateFailureException $e) {
	echo $e->getMessage();
}
```

### Programmatically add an update

[](#programmatically-add-an-update)

The `saveNewUpdate` method optionally takes a second argument containing the ID of the update. If left out, a new unique ID containing the date and a random hash (suggested) is used instead.

```
$updater->saveNewUpdate([
	'CREATE TABLE ...',
	'ALTER TABLE ...',
]);
```

Unit Tests
----------

[](#unit-tests)

The library contains some unit tests for each mode. To execute them, set the following environment variables and execute `composer test`:

- DB
- DB\_HOST
- DB\_USER
- DB\_PASS
- DB\_PORT

You can also adjust the phpunit.xml and enter your database credentials there.

###  Health Score

24

—

LowBetter than 32% of packages

Maintenance0

Infrequent updates — may be unmaintained

Popularity14

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity64

Established project with proven stability

 Bus Factor1

Top contributor holds 100% 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 ~32 days

Recently: every ~57 days

Total

9

Last Release

1633d ago

### Community

Maintainers

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

---

Top Contributors

[![dioncodes](https://avatars.githubusercontent.com/u/1241360?v=4)](https://github.com/dioncodes "dioncodes (28 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/tinyapps-db-updater/health.svg)

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

###  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.4k](/packages/illuminate-database)[mongodb/mongodb

MongoDB driver library

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

Use ramsey/uuid as a Doctrine field type.

90340.3M211](/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)