When building robust APIs with FastAPI, it’s crucial to handle application startup and shutdown events cleanly. Whether you’re setting up a database connection, initializing background tasks, or gracefully releasing resources, FastAPI provides the lifespan interface for managing these key moments. Let’s walk through how to use lifespan events effectively, clear up some common pitfalls, and review practical tips for integrating them into your services.

FastAPI Lifespan 101

Prior to version 0.95.0, you might have used @app.on_event('startup') and @app.on_event('shutdown') decorators. These still work, but the new lifespan API offers a cleaner, more flexible approach, letting you run setup and teardown code with the guarantee that asynchronous context managers are properly respected.

Here’s the basic scaffold:

from fastapi import FastAPI
from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Initialization code here
    print("App is starting...")
    yield
    # Cleanup code here
    print("App is shutting down...")

app = FastAPI(lifespan=lifespan)

Typical Use Cases

1. Creating and Cleaning up a Database Connection

Suppose your application needs a persistent database engine:

from sqlalchemy.ext.asyncio import create_async_engine

@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.engine = create_async_engine(DATABASE_URL)
    yield
    await app.state.engine.dispose()

You can then retrieve app.state.engine in your dependencies or routes.

2. Starting Background Tasks

from asyncio import create_task

async def periodic_job():
    while True:
        print("Job running...")
        await asyncio.sleep(10)

@asynccontextmanager
async def lifespan(app: FastAPI):
    job = create_task(periodic_job())
    yield
    job.cancel()

Common Pitfalls

• Accessing non-existent state: Remember, anything you attach to app.state inside the lifespan context is available only after startup and before shutdown. Referencing it before initialization may cause errors.
• Synchronous code: Use async context managers for non-blocking, robust resource management.
• Testing: When using a lifespan handler, make sure your test client is aware of it. Use with TestClient(app) as client: to trigger startup and shutdown events for accurate testing.

Pro Tips

• Wrap third-party asynchronous resources inside the lifespan handler. This makes your application more portable and testable.
• Centralize all app-wide initialization in the lifespan function instead of global scope code — it’s cleaner and makes dependency management predictable.

Summary

FastAPI’s lifespan events unlock more predictable and organized startup/shutdown routines for web applications. By leveraging these, you reduce side effects, boost reliability, and pave the way for clean deployments (especially in containerized/cloud platforms). If you haven’t switched from @app.on_event to lifespan context managers yet, give it a shot—your future self will thank you!

Happy coding!
— Fast Eddy