support multiple databases (#26)

CHANGES.md

@@ -2,6 +2,10 @@
 
 Unreleased
 
+- Support Flask-SQLAlchemy-Lite and plain SQLAlchemy, in addition to
+  Flask-SQLAlchemy. {pr}`26`
+- Support multiple databases, and multiple metadata per database. {pr}`26`
+
 ## Version 3.0.1
 
 Released 2024-02-22

docs/databases.md

@@ -0,0 +1,119 @@
+from sqlalchemy.orm import DeclarativeBase
+
+# Database Scenarios
+
+You can use Flask-Alembic with Flask-SQLAlchemy, Flask-SQLAlchemy-Lite, or plain
+SQLAlchemy. Alembic's single and multiple database templates are supported.
+
+## Flask-SQLAlchemy
+
+The default engine (`db.engine`) and metadata (`db.metadata`) will automatically
+be used. If multiple binds are configured, they (`db.engines`) will be used if
+multiple metadatas are configured in Flask-Alembic. Additional metadata
+(`db.metadatas`) will not be used automatically however, as it's not possible to
+know which are external and should not be migrated.
+
+## Flask-SQLAlchemy-Lite
+
+The default engine (`db.engine`) will automatically be used. Since
+Flask-SQLAlchemy-Lite does not manage the models, tables, or metadata itself,
+the metadata you define must be passed to `Alembic`.
+
+```python
+from flask_alembic import Alembic
+from sqlalchemy.orm import DeclarativeBase
+
+class Model(DeclarativeBase):
+    pass
+
+alembic = Alembic(metadatas=Model.metadata)
+```
+
+## Plain SQLAlchemy
+
+If you are not using either extension, but defining SQLAlchemy engines and
+models/metadata manually, you can pass them to `Alembic`. You can also do this
+when using either extension to control exactly what is used for migrations.
+
+```python
+from flask_alembic import Alembic
+from sqlalchemy import create_engine
+from sqlalchemy.orm import DeclarativeBase
+
+engine = create_engine("sqlite:///default.sqlite")
+
+class Model(DeclarativeBase):
+    pass
+
+alembic = Alembic(metadatas=Model.metadata, engines=engine)
+```
+
+## Multiple Databases
+
+If you need to manage migrations across multiple databases, you can specify
+multiple metadata and engines to run migrations on. Flask-Alembic will use
+Alembic's suggested `multidb` template for generating and running migrations.
+
+The `metadatas` argument can be a dict mapping string names to a single
+metadata or list of metadatas. When using Flask-SQLAlchemy(-Lite), `db.engines`
+is automatically used, so the keys there should match up with the keys in
+`metadatas`. Otherwise, the `engines` argument can be a dict mapping the same
+string names to engines.
+
+```python
+from flask import Flask
+from flask_alembic import Alembic
+from flask_sqlalchemy_lite import SQLAlchemy
+from sqlalchemy.orm import DeclarativeBase
+
+class DefaultBase(DeclarativeBase):
+    pass
+
+class AuthBase(DeclarativeBase):
+    pass
+
+db = SQLAlchemy()
+alembic = Alembic(
+    metadatas={
+        "default": DefaultBase.metadata,
+        "auth": AuthBase.metadata,
+    },
+)
+app = Flask(__name__)
+app.config["SQLALCHEMY_ENGINES"] = {
+    "default": "sqlite:///default.sqlite",
+    "auth": "postgresql:///app-auth",
+}
+db.init_app(app)
+alembic.init_app(app)
+```
+
+When `alembic.init_app` is called, it creates the migrations directory and
+script template if it does not exist. It will choose the `generic` (single
+database) template if only one name is configured, or the `multidb` template if
+more are configured. Due to the way Alembic works, the two templates are not
+compatible. If you switch to single or multiple databases later after generating
+migrations, you'll need to replace the `script.py.mako` file and modify the
+existing migrations. A good strategy in that scenario may be to delete existing
+migrations and start from scratch.
+
+## Multiple Metadatas
+
+It's possible to split your models/tables for a database across multiple
+metadatas. In that case, you can pass a list of metadatas instead of a single
+metadata. If you're only managing a single database, you can pass the list
+directly to `metadatas`, otherwise any value in the dict can be a list.
+
+
+```python
+from flask_alembic import Alembic
+from sqlalchemy.orm import DeclarativeBase
+
+class DefaultBase(DeclarativeBase):
+    pass
+
+class AuthBase(DeclarativeBase):
+    pass
+
+alembic = Alembic(metadatas=[DefaultBase.metadata, AuthBase.metadata])
+```

docs/index.md

@@ -1,17 +1,21 @@
 # Flask-Alembic
 
 Flask-Alembic is a [Flask][] extension that provides a configurable [Alembic][]
-migration environment around a [Flask-SQLAlchemy][] database.
+database migration environment. Supports [Flask-SQLAlchemy],
+[Flask-SQLAlchemy-Lite], or plain [SQLAlchemy]. Supports Alembic's single and
+multiple database templates.
 
 [Flask]: https://flask.palletsprojects.com
 [Alembic]: https://alembic.sqlalchemy.org
+[SQLAlchemy]: https://www.sqlalchemy.org
 [Flask-SQLAlchemy]: https://flask-sqlalchemy.palletsprojects.com
+[Flask-SQLAlchemy-Lite]: https://flask-sqlalchemy-lite.readthedocs.io
 
 ## Installation
 
-Install from [PyPI][]:
+Install from [PyPI][] using an installer such as pip:
 
-```text
+```
 $ pip install Flask-Alembic
 ```
 
@@ -21,6 +25,8 @@ $ pip install Flask-Alembic
 
 - Configuration is taken from `Flask.config` instead of `alembic.ini` and
   `env.py`.
+- Engines and model/table metadata are taken from Flask-SQLAlchemy(-Lite) if
+  available, or can be configured manually.
 - The migrations are stored directly in the `migrations` folder instead of the
   `versions` folder.
 - Provides the migration environment instead of `env.py` and exposes Alembic's
@@ -29,18 +35,19 @@ $ pip install Flask-Alembic
   revision objects and don't print to stdout.
 - Allows operating Alembic at any API level while the app is running, through
   the exposed objects and functions.
-- Does not (currently) support offline migrations. I don't plan to add this but
-  am open to patches.
-- Does not (currently) support multiple databases. I plan on adding support for
-  Flask-SQLAlchemy binds and external bases eventually, or am open to patches.
 - Adds a system for managing independent migration branches and makes it easier
   to work with named branches.
+- Does not (currently) support offline migrations. I don't plan to work on this
+  but am open to patches.
+- Does not (currently) support async engines. I don't plan to work on this but
+  am open to patches.
 
 ```{toctree}
 :hidden:
 
 use
 config
+databases
 branches
 api
 license

docs/use.md

@@ -6,7 +6,7 @@
 ```
 
 First, set up your Flask application (or application factory) and the
-Flask-SQLAlchemy extension and models.
+Flask-SQLAlchemy(-Lite) extension and models.
 
 This extension follows the common pattern of Flask extension setup. Either
 immediately pass an app to {class}`.Alembic`, or call {meth}`~.Alembic.init_app`
@@ -19,6 +19,26 @@ alembic = Alembic()
 alembic.init_app(app)  # call in the app factory if you're using that pattern
 ```
 
+When using Flask-SQLAlchemy, `db.engines` and `db.metadata` are used
+automatically.
+
+When using Flask-SQLAlchemy-Lite, `db.engines` is used automatically, but you
+must pass the metadata you defined.
+
+```python
+from flask_alembic import Alembic
+from sqlalchemy.orm import DeclarativeBase
+
+class Model(DeclarativeBase):
+    pass
+
+alembic = Alembic(metadatas=Model.metadata)
+```
+
+You can use Flask-Alembic with Flask-SQLAlchemy, Flask-SQLAlchemy-Lite, or plain
+SQLAlchemy, and there is support for migrating multiple databases. See
+{doc}`databases` for details.
+
 When an app is registered, the migrations directory is created if it does not
 exist.
 

pyproject.toml

@@ -20,7 +20,6 @@ requires-python = ">=3.8"
 dependencies = [
     "alembic>=1.13",
     "flask>=3.0",
-    "flask-sqlalchemy>=3.1",
     "sqlalchemy>=2.0",
 ]
 
@@ -74,7 +73,6 @@ select = [
     "UP",  # pyupgrade
     "W",  # pycodestyle warning
 ]
-ignore-init-module-imports = true
 
 [tool.ruff.lint.isort]
 force-single-line = true

requirements/dev.txt

@@ -8,6 +8,11 @@ alabaster==0.7.16
     # via
     #   -r docs.txt
     #   sphinx
+asgiref==3.8.1
+    # via
+    #   -r tests.txt
+    #   -r typing.txt
+    #   flask
 babel==2.14.0
     # via
     #   -r docs.txt
@@ -16,6 +21,11 @@ beautifulsoup4==4.12.3
     # via
     #   -r docs.txt
     #   furo
+blinker==1.8.2
+    # via
+    #   -r tests.txt
+    #   -r typing.txt
+    #   flask
 cachetools==5.3.2
     # via tox
 certifi==2024.2.2
@@ -30,6 +40,11 @@ charset-normalizer==3.3.2
     # via
     #   -r docs.txt
     #   requests
+click==8.1.7
+    # via
+    #   -r tests.txt
+    #   -r typing.txt
+    #   flask
 colorama==0.4.6
     # via tox
 distlib==0.3.8
@@ -43,8 +58,27 @@ filelock==3.13.1
     # via
     #   tox
     #   virtualenv
+flask[async]==3.0.3
+    # via
+    #   -r tests.txt
+    #   -r typing.txt
+    #   flask-sqlalchemy
+    #   flask-sqlalchemy-lite
+flask-sqlalchemy==3.1.1
+    # via
+    #   -r tests.txt
+    #   -r typing.txt
+flask-sqlalchemy-lite==0.1.0
+    # via
+    #   -r tests.txt
+    #   -r typing.txt
 furo==2024.5.6
     # via -r docs.txt
+greenlet==3.0.3
+    # via
+    #   -r tests.txt
+    #   -r typing.txt
+    #   sqlalchemy
 identify==2.5.33
     # via pre-commit
 idna==3.7
@@ -60,9 +94,17 @@ iniconfig==2.0.0
     #   -r tests.txt
     #   -r typing.txt
     #   pytest
+itsdangerous==2.2.0
+    # via
+    #   -r tests.txt
+    #   -r typing.txt
+    #   flask
 jinja2==3.1.3
     # via
     #   -r docs.txt
+    #   -r tests.txt
+    #   -r typing.txt
+    #   flask
     #   myst-parser
     #   sphinx
 markdown-it-py==3.0.0
@@ -73,7 +115,10 @@ markdown-it-py==3.0.0
 markupsafe==2.1.5
     # via
     #   -r docs.txt
+    #   -r tests.txt
+    #   -r typing.txt
     #   jinja2
+    #   werkzeug
 mdit-py-plugins==0.4.0
     # via
     #   -r docs.txt
@@ -183,12 +228,20 @@ sphinxcontrib-serializinghtml==1.1.10
     # via
     #   -r docs.txt
     #   sphinx
+sqlalchemy[asyncio]==2.0.30
+    # via
+    #   -r tests.txt
+    #   -r typing.txt
+    #   flask-sqlalchemy
+    #   flask-sqlalchemy-lite
 tox==4.15.0
     # via -r dev.in
 typing-extensions==4.9.0
     # via
+    #   -r tests.txt
     #   -r typing.txt
     #   mypy
+    #   sqlalchemy
 urllib3==2.2.0
     # via
     #   -r docs.txt
@@ -197,6 +250,11 @@ virtualenv==20.25.0
     # via
     #   pre-commit
     #   tox
+werkzeug==3.0.3
+    # via
+    #   -r tests.txt
+    #   -r typing.txt
+    #   flask
 
 # The following packages are considered to be unsafe in a requirements file:
 # setuptools

requirements/tests-3.8.in

@@ -0,0 +1,2 @@
+flask-sqlalchemy
+pytest