SQLAlchemy and Alembic failures: preserve local data before changing anything

Separate the failure layers

SQLAlchemy is a database toolkit; Alembic uses revision files to order migration operations. A missing Python module, a DBAPI operation failure and an unknown Alembic revision need different investigations. SQLAlchemy says the driver's detail inside an OperationalError matters: that class can cover a dropped connection, unavailable data source or failed transaction, among other causes. Do not infer that a database file should be deleted. SQLAlchemy overview SQLAlchemy errors Alembic tutorial

Preserve data before repair

1. Identify whether the database belongs to ComfyUI, a custom node or the launcher. Record the application version, database location or redacted connection target, exact error and current migration revision. Never post credentials in a connection string.

2. Follow that application's documented backup procedure before changing packages, revision tables or schema. Coordinate a consistent snapshot with the application; copying only a live database file is not automatically a recoverable backup. Test restoration and record counts or identifiers of existing data on an isolated copy.

3. If an import is missing, inspect the Python environment that actually launches the owning application and its declared dependency set:

python -m pip show SQLAlchemy alembic

This inventory command does not repair the environment. For OperationalError, preserve the driver message and inspect the actual target, availability, permissions and operation rather than assuming one cause. For Can't locate revision, compare the recorded database revision with the migration files shipped with the same application version. Alembic's current and history commands can help inspect an application-owned migration environment. SQLAlchemy errors Alembic tutorial

4. Do not use stamp head to make a failed upgrade appear complete. Alembic documents that stamp changes the revision table without running migrations, whereas upgrade executes the migration path. Only the owning application's documented recovery procedure can justify changing revision state or rebuilding a database. Alembic commands

Completion check and limits

On an isolated restored copy, verify that pre-existing records remain readable and the affected application operation works, including a controlled write if appropriate. A successful migration command exit alone does not prove data survived. This article does not identify your database owner or authorize deletion, downgrade or blind schema changes.

Source review: 2026-09-26. No local database, migration, restoration or GPU reproduction was performed.

Related checks

• Keep a reproducible ComfyUI repair record without exposing secrets
• Where to run ComfyUI commands: PowerShell, CMD and virtual environments