Defining Workflows
A workflow is a SQLAlchemy model with the Workflow mixin. This page shows how to declare one in a Reflex app, what the mixin adds to your table, and how to change a workflow once runs exist.
Choose a base for workflow tables
Declare workflows on a SQLAlchemy DeclarativeBase, such as the one your app's other tables use. The examples on these pages use a plain base:
from sqlalchemy.orm import DeclarativeBase
class Base(DeclarativeBase):
passIf your base uses MappedAsDataclass, as the one in the database docs does, take the mixins from reflex_workflow.dataclass instead; see Use dataclass models.
Reflex's migration commands find a base without being told about it, as long as the module that defines it holds it under its own name, such as Base or Namespace.Base, and your app imports that module. Register a base that Reflex can't find this way, such as one made by a factory function and bound to a different name. If your app registers bases with rx.ModelRegistry.register, register the workflow base too: once any base is registered, Reflex leaves out the ones that aren't, and reflex db makemigrations writes a migration that drops their tables.
You can't use rx.Model as a workflow base. rx.Model is a SQLModel, which is a pydantic model, and pydantic rejects the step methods the mixin collects.
Define a workflow
Mix Workflow into a model on that base. Your columns hold the state of each run:
from sqlalchemy import String
from sqlalchemy.orm import Mapped, mapped_column
from reflex_workflow import Workflow, step
class Expense(Base, Workflow):
__tablename__ = "expense"
id: Mapped[int] = mapped_column(primary_key=True)
request_id: Mapped[str] = mapped_column(String(64), unique=True)
amount: Mapped[int]
status: Mapped[str] = mapped_column(String(32), default="draft")
@step
async def submit(self):
self.status = "submitted"Any primary key works, including composite keys. Add a unique constraint on whatever identifies the work, such as request_id above: start never inserts a row that conflicts with an existing one, so the constraint is what stops a retried request from starting a second run.
Every workflow needs its own table. Two workflow classes with the same __tablename__ raise a ValueError.
Columns the mixin adds
The mixin adds twelve columns that the engine reads and writes. You can query them, but don't write to them directly: use start, run, cancel, and deliver instead.
The mixin also indexes the columns the engine searches on. Inspecting runs shows how to read these columns to tell where a run is.
Create the tables
Generate and apply a migration as you would for any model:
uv run reflex db makemigrations --message "add expense workflow"
uv run reflex db migrateThe migration includes the mixin's columns and indexes. As with any model, Reflex only sees workflows in modules your app imports. If you manage migrations with Alembic directly, set target_metadata = Base.metadata.
You can add the mixin to a table that already has rows. The two non-nullable columns it adds, attempts and wf_version, have server defaults, so the migration fills them in. Existing rows have no next_step, so they are finished runs; to give them something to do, use run.
Create a session factory
The engine needs an async_sessionmaker for the database that holds the workflow tables. In a Reflex app, build it on the async engine Reflex already creates from async_db_url, so the app has a single connection pool:
from reflex.model import get_async_engine
from sqlalchemy.ext.asyncio import async_sessionmaker
sessions = async_sessionmaker(get_async_engine(None), expire_on_commit=False)Keep expire_on_commit=False: the engine reads a row's columns after committing it. Don't reuse the session factory behind rx.asession(); its sessions are SQLModel sessions, which warn about the queries the engine makes.
Use the psycopg 3 driver (postgresql+psycopg://). It serves both the synchronous URL Reflex uses for migrations and the asynchronous one the workflows use, and it lets workers hear about new runs immediately.
Pass the factory to run_workflows or connect_workflows.
Use dataclass models
If your base uses MappedAsDataclass, import the mixins from reflex_workflow.dataclass instead. SQLAlchemy doesn't allow mixing a class that isn't a dataclass into one that is:
from sqlalchemy.orm import DeclarativeBase, Mapped, MappedAsDataclass, mapped_column
from reflex_workflow.dataclass import Workflow
class Base(MappedAsDataclass, DeclarativeBase, kw_only=True):
pass
class Onboarding(Base, Workflow):
__tablename__ = "onboarding"
id: Mapped[int] = mapped_column(primary_key=True, init=False)
email: Mapped[str]
nudges: Mapped[int] = mapped_column(default=0)The mixin's columns are declared with init=False, so the constructor takes only your own fields: Onboarding(email=...). AttemptLog and RateBucket are also available from reflex_workflow.dataclass. Both kinds of workflow can run in the same app.
Change a workflow that has runs
A run stores the name of its next step and that step's arguments, so changing steps affects runs already in the table.
- Adding a step is always safe.
- Changing a step's body is safe. Runs that reach the step after you deploy run the new code.
- Renaming or removing a step breaks the runs that still name it. A run scheduled for it fails when it comes due, and a run waiting on it no longer matches events sent to the new name. Keep the old step until no row's
next_steporwaiting_fornames it, or update those rows in the same migration. - Changing a step's parameters fails runs whose stored arguments no longer fit. Add new parameters with defaults so stored arguments stay valid.
To find the runs that still use a step, query the mixin's columns:
waiting = await Expense.by(
(Expense.next_step == "decide") | (Expense.waiting_for == "decide")
).all()