Lifespan Context vs Startup Event: Safe Recovery After a Failed Upgrade

Question

Choosing a Lifecycle Hook for Upgrade Safety
When deploying a FastAPI application, a failed upgrade can leave resources—such as database connections or external services—in an inconsistent state. FastAPI exposes two primary mechanisms for initializing and cleaning up resources: the lifespan context manager and the legacy @app.on_event('startup') / @app.on_event('shutdown') decorators. Both can be used to orchestrate pre‑start and post‑shutdown logic, but they differ in ordering guarantees, startup latency, and cleanup reliability.
The lifespan context guarantees that the shutdown block runs only after the startup block completes, even if an exception occurs during startup. In contrast, the older event decorators offer no explicit ordering, and a failure in a startup event may leave other events or dependencies partially initialized.
Given the need to recover cleanly from a mid‑upgrade crash, which approach provides a more robust foundation for safe rollback?
Specific Questions

Does the lifespan context manager ensure that all resources opened in its startup block are guaranteed to be closed in the shutdown block, even if the startup block raises an exception?
How does the startup event decorator’s lack of ordering affect the ability to roll back partially applied migrations or open connections during a failed upgrade?
What measurable impact does each approach have on application readiness time and the risk of orphaned resources in a production deployment?

Tasadduq Burney · Answer

Answer
For safe recovery after a failed upgrade, the lifespan context manager is the more robust foundation.

Confirmed facts

The lifespan context manager's shutdown block (code after yield) runs even if an exception occurs in the startup block (code before yield).
Legacy @app.on_event('startup') handlers lack ordering guarantees; a failure can prevent later startup handlers and their shutdown counterparts from executing.

Likely explanation
Because lifespan ties startup and shutdown together as a single async context manager, the cleanup code after yield is guaranteed to run via the __exit__ protocol, closing any resources that were successfully opened before the failure. Independent event decorators can leave some handlers executed and others not, leading to orphaned connections or partially applied migrations.

Steps to implement safe recovery

Define an async context manager lifespan that creates resources before yield.
Place cleanup logic after yield (wrap in a try...finally if needed).
Pass it to FastAPI(lifespan=lifespan).
Optionally, handle exceptions during resource creation to avoid leaving half‑initialized state.

Are you running database migrations inside the startup block, and if so, do they support automatic rollback on failure?

Lifespan Context vs Startup Event: Safe Recovery After a Failed Upgrade

Choosing a Lifecycle Hook for Upgrade Safety

Specific Questions

1 answer

Answer

Confirmed facts

Likely explanation

Steps to implement safe recovery

Your perspective belongs here.

0 question comments