alembic: documentation #88
Conversation
alembic.rst
Outdated
| @@ -0,0 +1,84 @@ | |||
| Alembic | |||
| ======= | |||
| Alembic is a database migration tool for usage with SQLAlchemy Database. The full documentation can be found here: | |||
There was a problem hiding this comment.
- can be found here: -> missing link
- s/tool for usage with SQLAlchemy Database/library used with the SQLAlchemy ORM/
alembic.rst
Outdated
| Alembic | ||
| ======= | ||
| Alembic is a database migration tool for usage with SQLAlchemy Database. The full documentation can be found here: | ||
| In invenio the alembic environment is already defined in invenio-db |
There was a problem hiding this comment.
Invenio-DB fully supports Alembic and each Invenio module having a database model is also expected to provide the corresponding alembic scripts.
alembic.rst
Outdated
| Creating new revisions | ||
| ---------------------- | ||
|
|
||
| When working with an invenio module that already has alembic revisions, after modifying a model we can create a new alembic revision with: |
There was a problem hiding this comment.
It would be better if users could follow the script from top to bottom without jumping back and forth. Also we need to explain as if the user just discovered alembic and/or invenio-db and does not now how to search for alembic scripts.
What do you think instead of this:
===
Create an alembic upgrade script
The following procedure will add an alembic upgrade script to invenio-unicorn for demonstration purpose.
First you need to check if your module has already some alembic scripts. Open the setup.py file and see if there is an invenio_db.alembic entrypoints property like this:
setup(
...
entry_points={
...
'invenio_db.alembic': [
'invenio_unicorn = invenio_unicorn:alembic',
]
...
})If there is one, go the the package invenio_unicorn.alembic and check if there is a python script in it. It should have a name similar to: 843bc79c426f_create_invenio_unicorn_branch.py (the numbers and letters at the beginning will not be the same).
If the setup.py file does not contain the invenio_db.alembic property or if the invenio_unicorn.alembic package is empty you need to create an upgrade branch first, continue to the next section. Otherwise you can skip the next section.
Adding Alembic support
... (setup.py + alembic branch)
Create the new upgrade script
...
alembic.rst
Outdated
|
|
||
| $ invenio alembic revision "Added some column." --path alembic_directory_path | ||
|
|
||
| A short message describing the changes is required and the path parameter should point to the alembic directory of the module. If the path is not given the new revision will be placed in the invenio_db/alembic directory. |
There was a problem hiding this comment.
If the path is not given the new revision will be placed in the invenio_db/alembic directory which is not the desired behavior.
alembic.rst
Outdated
|
|
||
| .. code-block:: console | ||
|
|
||
| $ invenio alembic upgrade heads |
There was a problem hiding this comment.
Shouldn't we start by running this before creating the new script so that everything is up to date? The user can normally run this without worrying about breaking anything as long as he didn't create his migration script.
alembic.rst
Outdated
| A short message describing the changes is required and the path parameter should point to the alembic directory of the module. If the path is not given the new revision will be placed in the invenio_db/alembic directory. | ||
|
|
||
| The directories accepted are registered by the invenio_db.alembic entrypoints. | ||
| If the DB has not been updated to show the last changes, there is some alembic revision that needs to be applied by: |
There was a problem hiding this comment.
It's not clear if this talks about the "last changes" as the newly created migration script or any previous script which was not yet ran.
alembic.rst
Outdated
|
|
||
| $ invenio alembic mkdir | ||
|
|
||
| in invenio_unicorn and add the invenio_db.alembic entrypoint in setup.py: |
There was a problem hiding this comment.
You can remove in invenio_unicorn and. The sentence is hard to read if it is split by code.
=> Add the invenio_db.alembic entrypoint in setup.py:
dinosk
force-pushed
the
alembic-doc
branch
4 times, most recently
from
56d0192
to
df0f229
Compare
dinosk
changed the title
dinosk
force-pushed
the
alembic-doc
branch
2 times, most recently
from
9b097d6
to
7ba9085
Compare
Signed-off-by: Dinos Kousidis <konstantinos.kousidis@cern.ch> Co-authored-by: Nicolas Harraudeau <nicolas.harraudeau@cern.ch>
No description provided.