Claude/ChatGPT Prompt to Migrate Flask from SQLAlchemy 1.x to 2.x

What this prompt does

This prompt frames the model as a Python engineer who has migrated production Flask apps from SQLAlchemy 1.x to 2.x, demanding a concrete ordered plan with real code diffs rather than a feature summary. You provide [app_profile], [current_version], [orm_style], and [risk_tolerance], and it returns a staged migration: pre-flight steps, query-API changes, typed mappings, deprecation removal, session/engine adjustments, and verification.

The structure works because ORM major-version jumps hide silent query-behaviour changes, and a big-bang rewrite is risky. [orm_style] tells the model what it's migrating from -- classic Query API versus already-modern usage -- so the diffs are relevant. [risk_tolerance] shapes how aggressive the rollout is, including whether to lean on the legacy compatibility flag. [current_version] and [app_profile] size the effort. Each step pairs before/after diffs with a rollback note, keeping the migration reversible at any point rather than committing you to finish once you start.

When to use it

• You're moving a Flask app from SQLAlchemy 1.x to 2.x and want a staged, ordered plan.
• You rely on the classic Query API and need to move to select() and Session.execute().
• You want typed Mapped[] columns in 2.x declarative mapping.
• You need to find and remove deprecated patterns before they break.
• You want each step paired with a code diff and a rollback note, not a summary.
• You're risk-averse and want to migrate behind the legacy compatibility flag first.
• You want session/engine and Flask-SQLAlchemy compatibility adjustments handled explicitly.

Example output

You get a numbered migration plan: pin versions and baseline tests, migrate the query API, convert to typed declarative mapping, strip deprecated patterns, fix session/engine and Flask-SQLAlchemy compatibility, then verify with warnings-as-errors. Each step carries before/after code diffs and a rollback note, so it reads as an executable runbook you can work through in order rather than a high-level overview you still have to break into tasks.

Pro tips

• Describe [orm_style] accurately (Classic Query API with declarative_base) so the diffs match how your code actually queries.
• Set [current_version] precisely so the legacy-flag and compatibility advice fits your starting point.
• Match [risk_tolerance] to reality -- low staged migration behind the legacy flag produces a more conservative rollout.
• Turn deprecation warnings into errors in CI before you start; that surfaces the real work fast.
• Treat it as a staged migration, never a big-bang rewrite -- the plan is ordered so each step is verifiable on its own.
• Use the rollback notes; if a step's diff misbehaves on your codebase, you want a defined way back.
• Convert mappings to typed Mapped[] columns in one pass per model so the diffs stay small and reviewable rather than sprawling across files.