Running migrations¶

Hint

To see all available options for these commands, use the --help flag, for example piccolo migrations forwards --help.

Forwards¶

When the migration is run, the forwards function is executed. To do this:

piccolo migrations forwards my_app

Multiple apps¶

If you have multiple apps you can run them all using:

piccolo migrations forwards all

Fake¶

We can ‘fake’ running a migration - we record that it ran in the database without actually running it.

There are two ways to do this - by passing in the --fake flag on the command line:

piccolo migrations forwards my_app 2022-09-04T19:44:09 --fake

Or by setting fake=True on the MigrationManager within the migration file.

async def forwards():
    manager = MigrationManager(
        migration_id=ID,
        app_name="app",
        description=DESCRIPTION,
        fake=True
    )
    ...

This is useful if we started from an existing database using piccolo schema generate, and the initial migration we generated is for tables which already exist, hence we fake run it.

Reversing migrations¶

To reverse the migration, run the following command, specifying the ID of a migration:

piccolo migrations backwards my_app 2022-09-04T19:44:09

Piccolo will then reverse the migrations for the given app, starting with the most recent migration, up to and including the migration with the specified ID.

You can try going forwards and backwards a few times to make sure it works as expected.

Preview¶

To see the SQL queries of a migration without actually running them, use the --preview flag.

This works when running migrations forwards:

piccolo migrations forwards my_app --preview

Or backwards:

piccolo migrations backwards 2022-09-04T19:44:09 --preview

Checking migrations¶

You can easily check which migrations have and haven’t ran using the following:

piccolo migrations check

Source¶

These are the underlying Python functions which are called, so you can see all available options. These functions are convered into a CI using targ.

async piccolo.apps.migrations.commands.forwards.forwards(app_name: str, migration_id: str = 'all', fake: bool = False, preview: bool = False)¶

Runs any migrations which haven’t been run yet.

Parameters:

app_name – The name of the app to migrate. Specify a value of ‘all’ to run migrations for all apps.
migration_id – Migrations will be ran up to and including this migration_id. Specify a value of ‘all’ to run all of the migrations. Specify a value of ‘1’ to just run the next migration.
fake – If set, will record the migrations as being run without actually running them.
preview – If true, don’t actually run the migration, just print the SQL queries

async piccolo.apps.migrations.commands.backwards.backwards(app_name: str, migration_id: str = '1', auto_agree: bool = False, clean: bool = False, preview: bool = False)¶

Undo migrations up to a specific migration.

Parameters:

app_name – The app to reverse migrations for. Specify a value of ‘all’ to reverse migrations for all apps.
migration_id – Migrations will be reversed up to and including this migration_id. Specify a value of ‘all’ to undo all of the migrations. Specify a value of ‘1’ to undo the most recent migration.
auto_agree – If true, automatically agree to any input prompts.
clean – If true, the migration files which have been run backwards are deleted from the disk after completing.
preview – If true, don’t actually run the migration, just print the SQL queries.

async piccolo.apps.migrations.commands.check.check(app_name: str = 'all')¶

Lists all migrations which have and haven’t ran.

Parameters:: app_name – The name of the app to check. Specify a value of ‘all’ to check the migrations for all apps.