Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix doc for Alembic helpers #386

Merged
merged 1 commit into from
Jun 17, 2022
Merged

Fix doc for Alembic helpers #386

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 16 additions & 14 deletions doc/alembic.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Interactions between some features of Alembic and GeoAlchemy 2 may lead to error
scripts, especially when using the ``--autogenerate`` feature of Alembic with the
``spatial_index=True`` feature of GeoAlchemy 2. In this case, the following errors occur:

1. the migration script miss the relevant imports from ``geoalchemy2``.
1. the migration script misses the relevant imports from ``geoalchemy2``.
2. the migration script will create the indexes of the spatial columns after the table is created,
but these indexes are already automatically created during table creation, which will lead to
an error.
Expand Down Expand Up @@ -109,13 +109,12 @@ Helpers

In order to make the use of Alembic easier, a few helpers are provided in
:ref:`geoalchemy2.alembic_helpers <alembic_helpers>`. These helpers can be used in the ``env.py``
file used by Alembic, like in the following example:
file used by Alembic to auto-generate the migration scripts, like in the following example:

.. code-block:: python

# ...
from geoalchemy2.alembic_helpers import include_object
from geoalchemy2.alembic_helpers import render_item
from geoalchemy2 import alembic_helpers
# ...

def run_migrations_offline():
Expand All @@ -137,8 +136,13 @@ file used by Alembic, like in the following example:
)
# ...

After running the ``alembic`` command, the migration script should be properly generated and should
not need to be manually edited.
After running the ``alembic revision --autogenerate -m <msg>`` command, the migration script should
be properly generated and should not need to be manually edited.

In this migration script you will notice specific spatial operation like `create_geospatial_table`,
`drop_geospatial_table`, `add_geospatial_column`, `drop_geospatial_column`, etc. These operations
can of course be edited manually in the migration scripts if you don't want to use auto-generation.
All specific operations can be found in :ref:`geoalchemy2.alembic_helpers <alembic_helpers>`.


Dealing with custom types
Expand All @@ -161,15 +165,14 @@ in ``my_package.custom_types``, you just have to edit the ``env.py`` file like t
.. code-block:: python

# ...
from geoalchemy2.alembic_helpers import include_object
from geoalchemy2.alembic_helpers import render_item as spatial_render_item
from geoalchemy2 import alembic_helpers
from my_package.custom_types import TheCustomType
# ...


def render_item(obj_type, obj, autogen_context):
"""Apply custom rendering for selected items."""
spatial_type = spatial_render_item(obj_type, obj, autogen_context)
spatial_type = alembic_helpers.render_item(obj_type, obj, autogen_context)
if spatial_type:
return spatial_type

Expand All @@ -183,7 +186,6 @@ in ``my_package.custom_types``, you just have to edit the ``env.py`` file like t
return False



def run_migrations_offline():
# ...
context.configure(
Expand Down Expand Up @@ -216,15 +218,15 @@ thus the ``env.py`` file should look like the following:

.. code-block:: python

from geoalchemy2.alembic_helpers import load_spatialite
from geoalchemy2.alembic_helpers import writer
from geoalchemy2 import alembic_helpers
from geoalchemy2 import load_spatialite


def run_migrations_offline():
# ...
context.configure(
# ...
process_revision_directives=writer,
process_revision_directives=alembic_helpers.writer,
render_item=alembic_helpers.render_item,
)
# ...
Expand All @@ -240,7 +242,7 @@ thus the ``env.py`` file should look like the following:
# ...
context.configure(
# ...
process_revision_directives=writer,
process_revision_directives=alembic_helpers.writer,
render_item=alembic_helpers.render_item,
)
# ...
5 changes: 1 addition & 4 deletions tests/test_alembic_migrations.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,10 +178,7 @@ def alembic_env(
connection = engine.connect()

def include_object(obj, name, obj_type, reflected, compare_to):
if obj_type == "table" and name.startswith("idx_"):
# Ignore SQLite tables used for spatial indexes
# TODO: Improve this condition!!!
return False
# Ignore tables that are already in the DB
if (
obj_type == "table"
and name not in [
Expand Down