Migrations¶
Migrations are provided through NXAlembic, a custom wrapper around Alembic that automatically configures it and provides compatibility with Nextcord-Ormar’s separate per-cog migration history.
Before Migrating¶
There are a couple things to know about how NXAlembic handles migrations
If you are coming from Django, Alembic cannot work purely from a migration history like Django. Alembic must have a live database to compare against to make migrations.
Table drops are not automatically detected. This was done to ensure Alembic wouldn’t accidentally delete tables if you do not have all of your cogs loaded at once. To drop a database, you can create a blank migration and add the drop yourself.
Alembic is currently unable to detect table name changes, column name changes, or anonymously named constraints. You can read more about Alembic’s limitations here.
Configuration¶
NXAlembic looks for a nxalembic.ini file in the current directory when run. This file should look something like
this.
[nxalembic]
module = example.demo
bot = bot
where module is the Python import path to your bot’s main script and bot is the name of your
nextcord_ormar.Bot instance. During migration, NXAlembic will import your bot out of this script to
examine the models instantiated by your cogs.
Usage¶
Alembic for Nextcord-Ormar
usage: nxalembic [-h] {migrate,upgrade,downgrade} ...
Positional Arguments¶
- tool
Possible choices: migrate, upgrade, downgrade
Alembic tool to use
Sub-commands:¶
migrate¶
Create a migration for a cog
This tool will compare your Ormar models against the database and generate a migration, which is a Python
script that can instruct the upgrade tool on how to modify your database. Unlike Alembic, it will not
generate blank migrations unless you pass --empty. It’s a good idea to inspect each migration produced
by NXAlembic before using them to upgrade your database.
nxalembic migrate [-h] [--app APP] [--empty] [--message MESSAGE]
options¶
- --app
App to create migration for. Defaults to all apps.
- --empty
Create a blank migration file.
Default: False
- --message, -m
Message to use for the migration.
Default: “”
upgrade¶
Upgrade a database app
nxalembic upgrade [-h] [--app APP] [--sql]
options¶
- --app
App to create migration for. Defaults to all apps.
- --sql
Generate SQL for this command instead of executing it.
Default: False
downgrade¶
Downgrade a database app
nxalembic downgrade [-h] [--sql] app
Positional Arguments¶
- app
App to create migration for. Defaults to all apps.
options¶
- --sql
Generate SQL for this command instead of executing it.
Default: False
Appendix¶
Why can’t I create database migrations without a database (ala Django?)¶
Here’s a write up from SQLAlchemy’s lead, Mike Bayer. In short, Alembic lacks the funding and manpower to implement the feature. Even Django had to put a Kickstarter together in order to fund one of their developers to work on it.