Database Migrations
CLI
handle_generate
Creates a new migration definition file, comparing the previous version (if it exists) with the current schema.
Parameters
- Name
package- Type
- str
- Description
The current python package name. This should match the name of the project that's specified in pyproject.toml or setup.py.
- Name
db_connection- Type
- DBConnection
- Description
- Name
message- Type
- str | None
- Description
Default: None
An optional message to include in the migration file. Helps with describing changes and searching for past migration logic over time.
python {{sticky: True}} from iceaxe.migrations.cli import handle_generate from click import command, option @command() @option("--message", help="A message to include in the migration file.") def generate_migration(message: str): db_connection = DBConnection(...) handle_generate("my_project", db_connection, message=message)
handle_apply
Applies all migrations that have not been applied to the database.
Parameters
- Name
package- Type
- str
- Description
The current python package name. This should match the name of the project that's specified in pyproject.toml or setup.py.
- Name
db_connection- Type
- DBConnection
- Description
handle_rollback
Rolls back the last migration that was applied to the database.
Parameters
- Name
package- Type
- str
- Description
The current python package name. This should match the name of the project that's specified in pyproject.toml or setup.py.
- Name
db_connection- Type
- DBConnection
- Description
Migrations
Base class for all revisions. This class is most often automatically
generated by the migrate CLI command, which automatically determines
the proper up and down revisions for your migration class.
Once added to your project, you can modify the up/down migration methods however you see fit.
Class Attributes
- Name
up_revision- Type
- str
- Description
- Name
down_revision- Type
- str | None
- Description
Class Methods
- Name
up- Return type
- Description
Perform the migration "up" action. This converts your old database schema to the new schema that's found in your code definition. Add any other migration rules to your data in this function as well.
It's good practice to make sure any up migrations don't immediately drop data. Instead, consider moving to a temporary table.
Support both raw SQL execution and helper functions to manipulate the tables and columns that you have defined. See the Migrator class for more information.
- Name
down- Return type
- Description
Perform the migration "down" action. This converts the current database state to the previous snapshot. It should be used in any automatic rollback pipelines if you had a feature that was rolled out and then rolled back.
Main interface for client migrations. Mountaineer provides a simple shim on top of
common database migration options within migrator.actor. This lets you add columns,
drop columns, migrate types, and the like. For more complex migrations, you can use
the migrator.db_session to run raw SQL queries within the current migration transaction.
Class Constructor
- Name
db_connection- Type
- DBConnection
- Description
The main database connection for the migration. Use this to run raw SQL queries. We auto-wrap this connection in a transaction block for you, so successful migrations will be automatically committed when completed and unsuccessful migrations will be rolled back.
Class Attributes
- Name
actor- Type
- DatabaseActions
- Description
The main interface for client migrations. Add tables, columns, and more using this wrapper.
Class Methods
- Name
init_db- Return type
- Description
Initialize our migration management table if it doesn't already exist within the attached postgres database. This will be a no-op if the table already exists.
Client callers should call this method once before running any migrations.
- Name
set_active_revision- Return type
- Description
Sets the active revision in the migration_info table.
- Name
get_active_revision- Return type
- str | None
- Description
Gets the active revision from the migration_info table. Requires that the migration_info table has been initialized.
Table Manipulator
Track the actions that need to be executed to the database. Provides a shallow, typed ORM on top of the raw SQL commands that we'll execute through asyncpg.
This class manually builds up the SQL strings that will be executed against postgres. We intentionally avoid using the ORM or variable-insertion modes here because most table-schema operations don't permit parameters to specify top-level SQL syntax. To keep things consistent, we'll use the same SQL string interpolation for all operations.
Class Constructor
- Name
dry_run- Type
- bool
- Description
Default: True
If True, the actions will be recorded but not executed. This is used internally within Iceaxe to generate a typehinted list of actions that will be inserted into the migration files without actually running the logic.
- Name
db_connection- Type
- DBConnection | None
- Description
Default: None
Class Attributes
- Name
dry_run_actions- Type
- list[DryRunAction | DryRunComment]
- Description
A list of actions that will be executed. Each arg/kwarg passed to our action functions during the dryrun will be recorded here.
- Name
prod_sqls- Type
- list[str]
- Description
A list of SQL strings that will be executed against the database. This is only populated when dry_run is False.
Class Methods
- Name
add_table- Return type
- Description
Create a new table in the database.
- Name
drop_table- Return type
- Description
Delete a table and all its contents from the database. This is a destructive action, all data in the table will be lost.
- Name
add_column- Return type
- Description
Add a new column to a table.
- Name
drop_column- Return type
- Description
Remove a column. This is a destructive action, all data in the column will be lost.
- Name
rename_column- Return type
- Description
Rename a column in a table.
- Name
modify_column_type- Return type
- Description
Modify the data type of a column. This does not inherently perform any data migrations of the column data types. It simply alters the table schema.
- Name
add_constraint- Return type
- Description
Adds a constraint to a table. This main entrypoint is used for all constraint types.
- Name
drop_constraint- Return type
- Description
Deletes a constraint from a table.
- Name
add_index- Return type
- Description
Adds a new index to a table. Since this requires building up the augmentary data structures for more efficient search operations, this migration action can take some time on large tables.
- Name
drop_index- Return type
- Description
Deletes an index from a table.
- Name
add_not_null- Return type
- Description
Requires data inserted into a column to be non-null.
- Name
drop_not_null- Return type
- Description
Removes the non-null constraint from a column, which allows new values to be inserted as NULL.
- Name
add_type- Return type
- Description
Create a new enum type with the given initial values.
- Name
add_type_values- Return type
- Description
Modifies the enum members of an existing type to add new values.
- Name
drop_type_values- Return type
- Description
Deletes enum members from an existing type.
This will only succeed at runtime if you have no table rows that currently reference the outdated enum values.
Note that dropping values from an existing type isn't natively supported by Postgres. We work around this limitation by specifying the "target_columns" that reference the enum type that we want to drop, so we can effectively create a new type.
- Name
drop_type- Return type
- Description
Deletes an enum type from the database.
- Name
add_comment- Return type
- Description
Only used in dry-run mode to record a code-based comment that should be added to the migration file.
::: iceaxe.schemas.actions.ColumnType
::: iceaxe.schemas.actions.ConstraintType