Alembic must be installed in the virtualenv in order to use right python paths,
so it's installed with pip. Commands described in this little documentation
must be executed from gargantext root directory, ie. /srv/gargantext.

Keep in mind that Alembic only handles SQLAlchemy models: tables created from
Django ORM must be put out of Alembic sight. See [alembic:exclude] section in
alembic.ini.


TELL ALEMBIC TO NOT START FROM SCRATCH

    # To upgrade a database populated before Alembic usage in Gargantext,
    # don't forget to tell Alembic your current version before to run
    # "upgrade head" command. If you don't want to do this, you can of course
    # drop your database and really start from scratch.

    alembic stamp bedce47c9e34


UPGRADE TO LATEST DATABASE VERSION

    alembic upgrade head


DOWNGRADE TO INITIAL DATABASE STATE

    # /!\ RUNNING THIS COMMAND WILL CAUSE ALL DATA LOST WITHOUT ASKING !!

    alembic downgrade base


GENERATE A NEW REVISION

    alembic revision -m "Message for this migration"

    # A migration script is then created in alembic/versions directory. For
    # example alembic/versions/3adcc9a56557_message_for_this_migration.py
    # where 3adcc9a56557 is the revision id generated by Alembic.
    #
    # This script must be edited to write the migration itself, mainly
    # in `upgrade` and `downgrade` functions. See Alembic documentation for
    # further details.


GENERATE A REVISION FROM CURRENT STATE

    alembic revision --autogenerate -m "Message for this migration"

    # Alembic should generate a script reflecting changes already made in
    # database. However it is always a good idea to check it and edit it
    # manually, Alembic is not always accurate and can't see all alterations.
    # It should work with basic changes such as model or column creation. See
    # http://alembic.zzzcomputing.com/en/latest/autogenerate.html#what-does-autogenerate-detect-and-what-does-it-not-detect