Alembic integration and documentation

[Jufik]

This is an to integrates Alembic within SqlModel (mentioned in #654)

Implementation is pretty straight forward and lays fundation to provide an extendible sqlmodel CLI through sqlmodel entrypoints. (though about Pluggy be felt like an overkill).

Current CLI structure is:

── sqlmodel
    └── migrations
        ├── init
        ├── revision
        ├── show
        ├── upgrade
        └── downgrade

Command are typed wrappers for the original alembic.command functions, exposed through Typer.
Usage and Documentation can be found in the advanced section.

More that glad to get any feedback or suggestions for improvements!

[github-actions]

📝 Docs preview for commit 32afa19 at: https://50871b3d.sqlmodel.pages.dev

[github-actions]

📝 Docs preview for commit 449882e at: https://f87a6f0c.sqlmodel.pages.dev

[github-actions]

📝 Docs preview for commit 0083a16 at: https://0f49201d.sqlmodel.pages.dev

[github-actions]

📝 Docs preview for commit b5944f0 at: https://e4e3fa97.sqlmodel.pages.dev

[github-actions]

📝 Docs preview for commit cc42afb at: https://c12e3a89.sqlmodel.pages.dev

[github-actions]

📝 Docs preview for commit 1eb82af at: https://ebd5efa7.sqlmodel.pages.dev

[Jufik]

Todo:

• Test Alembic methods / migrations for both templates.

One missing piece is around testing Alembic it self.
Glad to get any guidance on that.

Looking forward:

I am planning support some method called inside templates' env.py.

Main idea is to get the model from the config's alembic:target_metadata, pass it to a sqlmodel that would dynamically load the metadata.

I'd like some community feedback on such an idea.

[antont]

Seems like great work with the template and docs to me.

We've used the Alembic CLI for using Alembic with SQLModel, what benefits does this CLI offer? I'm not sure if it's useful to wrap Alembic to own CLI if it just passes on the calls to be done the same way as the upstream Alembic CLI does. But I did not read carefully what happens there, maybe it's helpful.

[Jufik]

Hey @antont,

At the moment not that much TBH 😅
Main idea is to provide the CLI fundations, but we could easily expand it further.
That moves FastApi/SqlModel one step closer to Django, and that opens few questions:

• Does this belong here ? Tiangolo seems to have a vision on this, and IDK how much this should be tied to FastAPI.
• Where is the limit, how simple should it be easy for developpers, with which restrictions ? (mostly: should cross-apps migration dependencies be handled ?)
• How opinionated should it be ?

[dimaqq]

I feel that adding a dependency needs a formal discussion.

On one hand, alembic is pretty lean, seems to only depend on sqlalchemy which this package already depends on too.

On the other, there are bound to be users that don't generate or apply migrations, rather consume some existing database instead. These users get a bit of bloat, and possibly a restriction on sqlalchemy versions they can use in their application.

This specific library addition may have been carefully thought through and may be OK.

A random library addition would be a problem.

Thus, I'd love to see a discussion and maintainer vote/rationale.

[antont]

As I mentioned above, we used alembic happily with sqlmodel, so maybe it's better indeed for sqlmodel to not depend on it, but just have things so that alembic can be used for it .. like it already can be.

Tiangolo does have this in the roadmap there so maybe he also has ideas for a tighter integration. I guess it could be also in an extra package, like sqlmodel-migrations, to avoid a runtime dep.

[jackbravo]

Maybe it should be a separate package, just like alembic is separated from sqlalchemy. That would also allow this to be released more easily and have people play with it, test it. Have you thought about releasing it @Jufik ?

[AmgadHasan]

Hey!
Will this be merged soon?

[hitchcock-william]

@tiangolo documentation in the advanced docs on migrations as well as the incorporation of something like this would be incredibly useful

[alessiamarcolini]

Hi @tiangolo is there an update on when this can be merged? 🙏 thank you so much for your work! ✨