Skip to content
Tutorials Center
My learning

Topics

Lesson 56 of 72 ยท Testing, Quality and Production

Async Views and Background Work

Understand async def views in Flask, when threads or worker processes help, and how task queues like Celery and RQ move slow work out of the request.

Some work does not belong inside a web request. Sending an email, resizing an image, building a report or calling three slow APIs can take seconds, and the visitor is staring at a spinner the whole time. While one request waits, the worker handling it can serve nobody else.

There are two separate ideas here, and mixing them up causes most of the confusion:

  • Concurrency inside a request. Do several slow waiting operations (network calls, mostly) at the same time instead of one after another. That is what async def views are for.
  • Work outside the request. Accept the request, hand the slow job to someone else, and answer right away. That is what background workers and task queues are for.

This lesson covers both, and shows a small runnable job queue so you can see the pattern without any infrastructure.

Async views in Flask

Since Flask 2.0 you can declare a view with async def. Install the extra that adds the helper library:

Terminal
pip install "flask[async]"

Then write the view as usual and use await inside it:

Python
import asyncio
import httpx
from flask import Flask

app = Flask(__name__)


@app.route("/dashboard")
async def dashboard():
    async with httpx.AsyncClient() as client:
        users, orders = await asyncio.gather(
            client.get("https://api.example.com/users"),
            client.get("https://api.example.com/orders"),
        )
    return {"users": users.json(), "orders": orders.json()}

This view needs a network, so it is read-only here. The important part is asyncio.gather(): both calls are started at once, and the view resumes when both have finished. The page takes as long as the slowest call, not the sum.

It is worth knowing what Flask does behind the scenes. Flask is still a WSGI framework. For an async def view it creates an event loop for that request, runs your coroutine on it until it finishes, and returns the result. The request still occupies one worker (a thread or a process) from start to finish.

flowchart LR
    R["Request arrives<br/>at a worker"] --> L["Flask starts an<br/>event loop"]
    L --> V["your async view runs,<br/>awaits several calls"]
    V --> X["loop finishes,<br/>response is returned"]

An async view makes one request faster by overlapping waits. It does not turn Flask into an event-driven server.

What that means in practice:

  • Async views help when one request makes several independent I/O calls. They do not make a single database query faster, and they do not help CPU-bound code at all.
  • They do not raise the number of requests a worker handles at once. For that, you need more workers or threads.
  • A task started with asyncio.create_task() is not guaranteed to outlive the request, because the loop is closed when the view returns. Do not use it for background work.
  • Anything needing long-lived connections (WebSockets, server-sent events with many clients) is better served by an ASGI framework such as Quart or FastAPI.
  • Mixing blocking calls (like requests.get) into an async def view blocks the loop. Use async libraries inside async views.

Seeing the benefit

Async views cannot run through the test client in the browser, because Flask needs to start its own event loop and the page already has one running. The idea itself is plain asyncio, though, and the next example shows exactly what gather buys you. Each "fetch" waits for a different time, standing in for a network call.

Python Sequential awaits versus gather

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Both versions return the same list, in the order the calls were written. But gather started all three waits together, so the total is roughly the longest delay (0.3 s) instead of the sum (0.6 s). That is the entire trick.

async def views are covered in more depth in the Python asyncio lesson. Flask only adds the bridge between its synchronous request handling and your coroutine.

Async database queries

Database calls are the most common thing you would want to overlap. Two facts decide how that works.

1. You need an async driver. A normal driver (psycopg2, PyMySQL, the sqlite3 module) blocks the event loop, so gather would run the queries one after another. SQLAlchemy 2 supports async through create_async_engine with an async driver: postgresql+asyncpg://, postgresql+psycopg:// (psycopg 3 supports async mode), mysql+aiomysql:// or sqlite+aiosqlite://.

2. One connection runs one query at a time. gather over two queries on the same connection or session still executes them one after the other. To get real overlap, each concurrent task needs its own AsyncSession (which borrows its own connection from the pool).

This read-only sketch shows the pattern for a dashboard view (it needs a real database and pip install "flask[async]" sqlalchemy asyncpg):

Python
import asyncio
import os

from flask import Flask
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from sqlalchemy.pool import NullPool

app = Flask(__name__)

engine = create_async_engine(os.environ["ASYNC_DATABASE_URL"], poolclass=NullPool)
Session = async_sessionmaker(engine, expire_on_commit=False)


async def count_rows(model):
    async with Session() as session:                      # its own session -> its own connection
        return await session.scalar(select(func.count()).select_from(model))


@app.get("/dashboard")
async def dashboard():
    users, orders, products = await asyncio.gather(
        count_rows(User), count_rows(Order), count_rows(Product)
    )
    return {"users": users, "orders": orders, "products": products}

Notice poolclass=NullPool. As explained above, Flask runs each async view on a fresh event loop. Network connections created by async drivers belong to the loop that opened them, so a pooled connection reused by a later request (on a different loop) fails with errors like "attached to a different loop". NullPool opens a connection per use and closes it afterwards, which is correct but gives up pooling. If database latency matters, run a pooler such as PgBouncer in front of the database, or use a native ASGI framework (Quart, FastAPI) where one long-lived loop owns the pool.

Also remember:

  • Flask-SQLAlchemy is synchronous. Do not use db.session inside async def views; it would block the loop. Use a separate async engine as above, or keep the view synchronous and let a thread pool run it.
  • Async lazy loading does not exist: accessing an unloaded relationship raises an error. Load what you need with selectinload() / joinedload() in the query.
  • Each concurrent session uses one connection, so gather of 20 tasks wants 20 connections at once. Limit concurrency (an asyncio.Semaphore) to stay under the database's max_connections.
  • If all you have is a synchronous driver, await asyncio.to_thread(sync_function) runs the blocking call on a worker thread so that it can overlap with other work.

Seeing why sessions matter

The next example replaces the database with a tiny fake that behaves like the real thing in the one way that matters here: every connection handles a single query at a time (a lock), and each query takes 0.2 seconds. Compare running three queries on one shared connection with running them on three connections from a pool.

Python One connection versus a pool of connections

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The shared connection and the one-connection pool take about 0.6 seconds (the sum), while three connections finish in about 0.2 seconds (the longest query). gather only allows overlap; whether queries actually run together depends on the connections underneath.

Async ORMs: Tortoise and async SQLAlchemy

Calling a blocking database driver from an async def view stops the event loop while the query runs, so async views only pay off with async drivers. Two common choices:

  • SQLAlchemy 2 async (create_async_engine, AsyncSession, with drivers such as asyncpg or aiosqlite).
  • Tortoise ORM, a Django-like ORM that is async from the ground up: models are classes with fields, queries are awaited.
Python
# Tortoise ORM (read-only: needs the tortoise-orm package)
from flask import Flask, jsonify
from tortoise import Tortoise, fields, run_async
from tortoise.models import Model

class User(Model):
    id = fields.IntField(primary_key=True)
    name = fields.CharField(max_length=80)

app = Flask(__name__)

async def init_tortoise():
    await Tortoise.init(db_url="sqlite://app.db", modules={"models": ["__main__"]})
    await Tortoise.generate_schemas()

run_async(init_tortoise())                       # one-time setup, before serving

@app.post("/add-user/<name>")
async def add_user(name):
    user = await User.create(name=name)          # awaited, so the loop stays free
    return jsonify(id=user.id, name=user.name), 201

@app.get("/user/<int:user_id>")
async def get_user(user_id):
    user = await User.get_or_none(id=user_id)
    return (jsonify(id=user.id, name=user.name), 200) if user else (jsonify(error="not found"), 404)

The catch is that Flask creates a new event loop for every async view call, but async database connections belong to one loop. Connection pools opened at start-up may then fail with "attached to a different loop" errors. Two safe patterns: open and close the connection inside the view, or run Flask under an ASGI server and use a framework made for it. For the occasional blocking job, concurrent.futures.ThreadPoolExecutor().submit(...) (or a task queue, below) is simpler than an async ORM.

Threads, processes and workers

A WSGI server such as gunicorn handles several requests at once with workers. Each worker is a separate operating-system process (that is why caches in memory are not shared), and each can run several threads. A request occupies one thread until its response is sent.

  • More processes use more CPU cores and survive a crash in one worker.
  • More threads let one process overlap I/O waits cheaply, but all threads share the interpreter's memory, so shared state needs care.
  • Async or green-thread workers (gevent, for example) can hold many waiting connections with little memory, but your libraries must cooperate.

It is tempting to start a threading.Thread inside a view to "do the slow part in the background". This works for tiny jobs but has real problems: the thread dies if the worker restarts, nothing records whether it finished, you cannot retry it, and there is no limit on how many pile up. Browser-based examples cannot create threads at all, so here is the read-only version of the pattern and why it is fragile:

Python
import threading


@app.route("/signup", methods=["POST"])
def signup():
    user = create_user(request.form)
    threading.Thread(target=send_welcome_email, args=(user.id,)).start()
    return "Welcome!", 201

If the server restarts one second later, the email is lost, and nobody knows. A proper background system is better.

Task queues

A task queue splits the work into three parts:

  1. The web app puts a job description (a function name and its arguments) on a queue and returns immediately.
  2. A broker, such as Redis or RabbitMQ, stores the queue safely.
  3. One or more worker processes, running separately from the web server, take jobs off the queue and run them.
sequenceDiagram
    participant C as Client
    participant F as Flask app
    participant Q as Queue (broker)
    participant W as Worker
    C->>F: POST /reports
    F->>Q: enqueue job
    F-->>C: 202 Accepted + job id
    W->>Q: take next job
    W->>W: run the slow task
    W->>Q: store result
    C->>F: GET /jobs/id
    F-->>C: status and result

The web request ends as soon as the job is queued. The client checks the result later.

The two most common Python tools are Celery (powerful, many features, more setup) and RQ (small, Redis-only, easy to learn). Others include Dramatiq and Huey. They need a running broker and worker, so these snippets are read-only:

Python
# RQ: a task is any importable function
from redis import Redis
from rq import Queue

queue = Queue(connection=Redis())


@app.route("/reports", methods=["POST"])
def create_report():
    job = queue.enqueue(build_report, request.json["month"])
    return {"job_id": job.id}, 202
Python
# Celery: tasks are declared with a decorator
from celery import shared_task


@shared_task(bind=True, max_retries=3)
def send_welcome_email(self, user_id):
    try:
        deliver_email(user_id)
    except ConnectionError as error:
        raise self.retry(exc=error, countdown=30)
Terminal
rq worker                                # start an RQ worker
celery -A myapp.celery worker --loglevel=info   # start a Celery worker

Whichever tool you use, remember that a worker is a different process. It does not have your request, your session or your g. Pass plain, serializable arguments such as ids, and let the worker load fresh data itself. If the task needs the Flask app (for the database or configuration), it must create or enter an application context. You'll find the details in Hooks, Application Context and g.

A runnable job queue

The concepts are easy to see in a tiny stand-in. This queue lives in memory and is processed by an explicit work_one() call, because the browser cannot run a separate worker process. It follows the usual API shape: submit returns 202 with a job id; a status endpoint reports queued, then done or failed.

Python A job queue behind a 202 response

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The POST returns at once with 202 Accepted and a Location header pointing at the status URL. At that moment both jobs are only queued. After the worker loop runs, the first job is done and the second failed with its error message recorded. A real front end would poll the status URL every second or two, or you could notify it with an email or a push message.

Retries and failure

Background jobs fail for boring reasons: a mail server is briefly down, a network call times out. Good systems retry with a growing delay (exponential backoff) and give up after a limit, keeping the failed job somewhere you can inspect it. Jobs should also be idempotent: running one twice must not charge a customer twice. Often you achieve this by storing "already done" in the database and checking it first.

Python Retry with exponential backoff

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Celery and RQ implement the same loop for you, with persistent storage and workers that survive restarts.

Choosing an approach

Situation Good fit
One request needs three independent API calls async def view with asyncio.gather
Sending email, thumbnails, exports, webhooks Task queue (RQ or Celery)
Nightly cleanup, daily digests Scheduled job (cron, Celery beat, systemd timer)
Live updates to many browsers ASGI framework or a dedicated service
Tiny, loss-tolerant side work A thread may be acceptable, with eyes open

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the main benefit of an async def view in Flask?

    An async view helps a single request do multiple independent waits at once. It does not add parallelism for CPU work, and Flask still handles the request as a WSGI app.
  2. 2. Why is starting a threading.Thread in a view a weak way to send emails?

    A plain thread has no persistence, no status, no retry and no limit. A task queue stores jobs outside the web process.
  3. 3. Which status code fits a POST that queues a job for later?

    202 means the request was accepted for processing but is not finished. A Location header can point to a status endpoint.
  4. 4. What should you pass to a background task as its arguments?

    A worker runs in another process with no request or session. Pass simple values and let the worker load what it needs.
  5. 5. What does it mean for a task to be idempotent?

    Because queues may deliver a job more than once (retries, crashes), tasks should be safe to repeat.

Summary

  • async def views let one request overlap several waiting operations; Flask still runs each request on a worker, and background tasks started in the view are not guaranteed to survive it.
  • Async database access needs an async driver and one AsyncSession (one connection) per concurrent task; Flask-SQLAlchemy is synchronous, and a fresh event loop per request means NullPool or an external pooler.
  • Workers are processes, optionally with threads; use more of them for more simultaneous requests.
  • Slow or unreliable work (email, exports, webhooks) belongs in a task queue such as RQ or Celery with a broker and separate worker processes.
  • The usual pattern: enqueue, return 202 Accepted plus a status URL, and let the client poll.
  • Pass ids and other simple values to tasks, make them idempotent, and retry with backoff.

Next, put everything on a real server in Deployment.