Migration with Alembic

Whenever the database structure is changed, developers should update migration instructions for the database using alembic. The default ngshare configuration automatically upgrades the database when starting.

Upgrade Database

This is automatically done in vanilla ngshare and vngshare implementations.

cd ngshare
python3 dbutil.py upgrade head

Create New Version

After a change is made in ngshare/database/database.py, use the following command to generate a migration script.

“It is always necessary to manually review and correct the candidate migrations that autogenerate produces.”

cd ngshare
python3 dbutil.py revision --autogenerate -m "MESSAGE"
vi alembic/versions/REVID_MESSAGE.py

MESSAGE is your message for the update.

REVID is the revision ID generated by Alembic.

ngshare runs data migration using Alembic (see Decisions), and the default configuration performs the migrations automatically. So make sure write test cases for the data migration in order to minimize the chance for Alembic upgrade to crash.

Reference

Update History

  • aa00db20c10a_init.py: initialize database

  • 1921a169739b_add_file_size.py: add file size column in File table. If file not found during data migration, File.size will be None.