For AI agents: the complete documentation index is at llms.txt. Remove the trailing slash from a page URL and append .md to read its Markdown version. For the docs home, use index.md.

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):
    pass

If 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.

ColumnHolds
next_stepThe name of the step that runs next. NULL once the run has nothing scheduled.
next_argsThe arguments for next_step, as JSON.
wake_atWhen next_step is due.
attemptsHow many times in a row the current step has failed.
last_errorThe error from the most recent failed attempt. Cleared when a step succeeds.
claimed_untilWhen the claim of the worker running the step expires.
waiting_forThe step an incoming event would run, while the run waits for one.
pending_eventAn event that arrived before the run started waiting for it.
recent_event_keysThe keys of the last 16 events the run accepted.
parentThe run that started this one with fan_out, if any.
children_leftHow many children of a fan_out have yet to finish.
wf_versionA counter that goes up whenever the run moves on. The engine uses it to discard commits from steps that were overtaken.

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 migrate

The 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_step or waiting_for names 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()