Migrations

The CLI migration commands wrap playhouse.migrations, available in peewee 4.4 or newer. Peewee migrations are python scripts, applied in numeric order and recorded by name in a history table. Each script defines up(migrator, db) and, if it can be reverted, down(migrator, db). The migrator is a SchemaMigrator (docs).

Configuration options:

• MIGRATIONS_DIR: directory for migration scripts, default migrations.

• MIGRATIONS_TABLE: history table name, default schema_migration.

Example

Write and apply an initial migration for the app’s models:

$ flask fp initial
migrations/0001_initial.py

$ flask fp up
applied: 0001_initial

Add a field to a model:

class User(db.Model):
    username = CharField()
    karma = IntegerField(default=0)

diff prints what changed (we added the “karma” field), and generate writes the migration:

$ flask fp diff
add column user.karma

$ flask fp generate "add karma"
migrations/0002_add_karma.py

The generated migration script:

# Generated from a schema diff on 2026-08-22 16:54.
from peewee import *

def up(migrator, db):
    migrator.migrate(migrator.add_column('user', 'karma', IntegerField(default=0)))


def down(migrator, db):
    migrator.migrate(migrator.drop_column('user', 'karma'))

Apply it (up) and review the history (status). Applied migrations show a marker and timestamp:

$ flask fp up
applied: 0002_add_karma

$ flask fp status
[x] 0001_initial  2026-08-22 16:54:02
[x] 0002_add_karma  2026-08-22 16:54:03

down reverts the newest migration, or back through an optional target:

$ flask fp down
reverted: 0002_add_karma

create writes an empty skeleton migration for any changes you prefer to write manually.

fake records migrations as applied without running them, for adopting migrations on a database that already matches the models.

More details on Peewee’s migration runner can be found in the migration runner docs.