Modifying the Database¶
Sometimes new features require modifying the database, such as adding a new column. Implementing such changes is fine, but can cause compatibility problems for users who are using an older version of the database schema. To resolve this issue, we use alembic to handle database migrations.
To use alembic to migrate the database schema, first run the following command:
python -m nbgrader.dbutil revision -m "a description of the change"
This will create a file in the directory
nbgrader/alembic/versions/7685cbef311a_foo.py. You will now need to
downgrade() functions in this file such that
they appropriately make the database changes. For example, to add a column
extra_credit to the
def upgrade(): op.add_column('grade', sa.Column('extra_credit', sa.Float)) def downgrade(): op.drop_column('grade', 'extra_credit')
Please see the alembic documentation for further details on
how these files work. Additionally, note that you both need to update the
database schema in
nbgrader/api.py (this describes how to create new
databases) as well as using alembic to describe what changes need to be made to
You can test whether the database migration works appropriately by running:
nbgrader db upgrade
on an old version of the database.