Extensions

Migrate

Alright, now that we are familiar with SQLAlchemy, the logical next step is keeping your database up to date. And that's the point where we should talk about migrating your database. Of course, we do already provide an extension for that as well.

Working with Migrate

Migrate is a CLI-only extension for WebFluid that provides single- and multi-db Alembic templates, enrolls the matching one based on your app configuration and manages your migrations for each of your projects' apps. In general, it is a wrapper for alembic commands with improved compatibility for WebFluid.

Anyway, since your main.py file is not executed when working with Migrate, it is time to outsource our config class into the apps' config.py file. Migrate uses the frameworks' magic we talked about in Config classes to parse the config and evaluate which template to use when it gets initialized:

fluid/config.py python 
from webfluid.core.config import register_config
import os


@register_config(10)
class MyConfig:
    SESSION_COOKIE_SECURE = True

    MYEXT_BAR = "crazy"

    # To test both templates we will create a second app later on
    # and uncomment the SQLALCHEMY_BINDS only for the second one:
    # SQLALCHEMY_BINDS = {
    #     "test": os.getenv("TEST_DB_URI", "sqlite:///test.db")
    # }


# You do not need to import this file manually, the framework
# initializes it automatically if it exists.

Preparing for migration

Okay, let's update your models so we've got something to migrate:

fluid/config.py python 
from webfluid.core.ext import db
from sqlalchemy import func
from sqlalchemy.orm import Mapped, mapped_column
from datetime import datetime


class MyModel(db.Model):
    id: Mapped[int] = mapped_column(primary_key=True)
    value: Mapped[str]
    created_at: Mapped[datetime] = mapped_column(
        server_default=func.now()
    )

    def __init__(self, value: str):
        self.value = value


class SecondModel(db.Model):
    __bind_key__ = "test"

    id: Mapped[int] = mapped_column(primary_key=True)
    value: Mapped[str]
    created_at: Mapped[datetime] = mapped_column(
        server_default=func.now()
    )

    def __init__(self, value: str):
        self.value = value

And integrate the update into your app. It is important to switch to the app factory setup, because Migrate assumes you are working with an app factory in your main.py file:

fluid/config.py python 
from webfluid import Fluid
from webfluid.core.ext import scheduler, db
from fastapi import Request
from fastapi.responses import HTMLResponse
from fastapi.exceptions import HTTPException
from apscheduler.triggers.interval import IntervalTrigger
from sqlalchemy import select

from extension.main import MyExtension
from fluid.jobs import heart
from fluid.models import MyModel

my_ext = MyExtension()
scheduler.add_job(heart, IntervalTrigger(seconds=5))


async def home():
    return await fluid.render(
        "index.html",
        title="Hello World!",
        name="my friend"
    )


async def health():
    return {"status": "ok"}


async def get_model(request: Request):
    model_id = request.query_params.get("id")
    if not model_id:
        raise HTTPException(status_code=400, detail="Bad Request")

    async with db.async_executor(model=MyModel) as e:
        results = await e.exec(
            select(MyModel).where(MyModel.id == model_id)
        )
        result = results.first()
        if not result:
            raise HTTPException(status_code=404, detail="Model not found")

        timestamp = result.created_at
        return {
            "model_id": model_id,
            "value": result.value,
            "created_at": timestamp.isoformat() if timestamp else None
        }


async def add_model(request: Request):
    data = await request.json()
    value = data.get("value")
    if not value:
        raise HTTPException(status_code=400, detail="Bad Request")

    async with db.async_executor(model=MyModel) as e:
        model = await e.insert(
            MyModel(value),
            flush=True
        )
        return {
            "model_id": model.id,
            "value": model.value,
            "created_at": model.created_at.isoformat()
        }


def create_app() -> Fluid:
    app = Fluid(__name__)

    app.get("/", response_class=HTMLResponse)(home)
    app.get("/health")(health)
    app.get("/my-model")(get_model)
    app.post("/my-model")(add_model)

    my_ext.expand_fluid(app)

    return app


if __name__ == "__main__":
    fluid = create_app()
    fluid.mix()

Single-DB

Now everything is set in place, and we can start migrating your databases using the Migrate CLI. This is done in three commands:

terminal bash 
# Initialize Migrate to get to correct alembic template
wf migrate init app

# Create the 'additives' directory because of
# the bug we mentioned in the overview page
mkdir additives

# Perform revision with autogenerate
wf migrate revision app -a

# Upgrade your database
wf migrate upgrade app

# And test it (do not forget to set
# EXT_SQLALCHEMY = 1 in your app.ini before):
wf run app

Multi-DB

Alright, now let's test the same thing with multiple binds:

terminal bash 
# Copy your app config:
cp app_configs/app.ini app_configs/app2.ini

# Now set your DATABASE_URI to sqlite:///app2.db
# and optionally add a TEST_DB_URI if you want.
# Then uncomment the SQLALCHEMY_BINDS in your config.

# The procedure is exactly the same:
wf migrate init app2
wf migrate revision app2 -a
wf migrate upgrade app2

wf run app2
 

The multi-db alembic template is currently not working and will be fixed within the next alpha release.

Continue reading

From here you can continue straight with Mail.