Development use cases

Examples:

  • Change behaviour of an existing API operation.

  • Change the API definition.

  • Change behaviour of background task.

  • Cleaning and restarting the development environment.

  • Change client behavior.

  • Tag a new version.

  • Update clients.

Create or modify a database model

This is done with SQLAlchemy. The procedure is to create a class like:

from quetzal.app import db


class Foo(db.Model):
    # ... contents, according to SQLAlchemy ...
    ...

Normally, this goes into the :py:module:`quetzal.app.models` module.

You should also add it to the dictionary created in the make_shell_context function inside the quetzal.app.create_app() factory function. This will automatically import the model when running flask shell.

Now, proceed to the Migrations procedure.

Migrations

Prepare a migration script

When creating or modifying a database model object, you need to make a migration script. This is done with alembic:

flask db migrate --rev-id ID -m MESSAGE

Here, ID is a revision identifier. Please use 0001, 0002, … and so on, according to the number of the files in the migrations/ directory. MESSAGE should be a short description of what the migration does.

Note that if you are running a development instance, you may need to set some environment variables for the command above to work. For example:

FLASK_ENV=development DB_HOST=localhost DB_USERNAME=postgres DB_PASSWORD=pg_password flask db migrate --rev-id ID -m MESSAGE

The flask db migrate command above will create a script called migrations/yyyymmdd_ID_MESSAGE.py. Read and review its contents. It is important to remove any database modification that does not correspond to what you have created or modified in your models. Alembic does most of the job to create this for you, but it does make mistakes.

Apply a migration script

Finally to apply your migration:

flask db upgrade head

Whenever there is a model database modification and you update Quetzal, you need to run the migration script.