WingCash Forum

Developer Tips and Questions

This topic is for developers of WingCash. Let’s add posts to this topic about how to get things done and where to find things. All useful info posted here is a candidate for inclusion in the WingCash developer documentation. Questions are also welcome here.

How to create a database migration script in wcbuild

  1. Make all changes you need to the SQLAlchemy declarations in wingcash.agents. Add/remove/modify tables and columns as needed.

  2. When you’re ready to test your new code, type bin/reset if you made any schema changes. The reset script deletes, re-creates, and repopulates the private Postgres database. You may want to enhance the populate script so you don’t have to manually repopulate after every reset.

  3. With Supervisor running, type:

    bin/dumpschema schema-after

    That command dumps the table definitions to 3 files in a directory called schema-after.

  4. Commit or stash your changes using git, then use git checkout to revert to a version without your schema changes. Dump the old schema to a new subdirectory called schema-before:

    bin/supervisorctl shutdown
    bin/builout
    bin/reset
    bin/dumpschema schema-before

  5. Optionally, make a backup now so you don’t have to revert to this version again in case you have to fix the migration script later:

    bin/backup backup-before

  6. Use git checkout to resume normal development on your branch.

  7. List all the changes like this:

    diff -Naur schema-before schema-after

  8. Write the migration script(s) based on the diff. The schema file often contains most of the SQL you need to put in the migration script(s).

  9. Update the schema version(s) in buildout.d/base.cfg and run bin/buildout.

  10. Commit your migration script using git.

  11. Run bin/supervisord to test your migration. Look at var/log/app and ensure the migration happened.

  12. Run bin/dumpschema schema-migrated and diff -Naur schema-after schema-migrated to ensure the migrated schema is functionally equivalent to the expected schema.

  13. If you made any mistakes, fix the migration script and commit it; to test it, first restore the database backup you created earlier:

    bin/restore backup-before
    bin/supervisord

This may sound like a lot of steps, but it becomes simple once you’ve done it a few times.