freshrss/edge/docs/en/developers/Minz
migrations| modified | Tuesday 15 September 2026 |
|---|
Migrations are the way to modify the database or the structure of files under the data/ path.
Migrations are placed under the app/migrations folder.
Good practice is to prepend the filename by the current date and explain what does the migration do in few words (e.g. 2020_01_11_CreateFooTable.php).
The files must contain a class which name starts with FreshRSS_Migration_, followed by the basename of the file (e.g. FreshRSS_Migration_2020_01_11_CreateFooTable).
The class must declare a migrate static function. It must return true or a string to indicate the migration is applied, or false otherwise. It can also raise an exception: the message will be used to detail the error.
Example:
1// File: app/migrations/2020_01_11_CreateFooTable.php
2class FreshRSS_Migration_2020_01_11_CreateFooTable {
3 public static function migrate() {
4 $pdo = new Minz_PdoSqlite('sqlite:/some/path/db.sqlite');
5 $result = $pdo->exec('CREATE TABLE foos (bar TEXT)');
6 if ($result === false) {
7 $error = $pdo->errorInfo();
8 raise Exception('Error in SQL statement: ' . $error[2]);
9 }
10
11 return true;
12 }
13}
They are automatically applied one by one when a user accesses FreshRSS.
Before being applied, migrations are sorted by filenames (see the strnatcmp function). Already applied migrations are skipped (the list can be found in the data/applied_migrations.txt file).
To ensure migrations are not applied several times if two users access FreshRSS at the same time, a folder named data/applied_migrations.txt.lock is created, then deleted at the end of the process.