无法为Alembic设置Cloud Spanner方言，求解决方案

已安装以下Python包：

SQLAlchemy==1.4.41
sqlalchemy-spanner==1.2.2
alembic==1.8.1

相关配置与代码如下：

1. main.py（Cloud Spanner的SQLAlchemy引擎配置）：

from sqlalchemy import create_engine, MetaData
from sqlalchemy.ext.declarative import declarative_base

engine = create_engine(
    "spanner+spanner:///projects/spanner-project/instances/spanner-instance/databases/spanner-database"
)
metadata = MetaData()
Base = declarative_base(metadata=metadata)

2. alembic.ini（数据库URL配置）：

sqlalchemy.url = spanner+spanner:///projects/spanner-project/instances/spanner-instance/databases/spanner-database

3. env.py（Alembic元数据设置）：

from app.main import Base
target_metadata = Base.metadata

4. models.py（数据模型定义）：

from app.main import Base
from sqlalchemy import (
    Column,
    Integer,
    String,
)


class Users(Base):
    __tablename__ = "users"
    __table_args__ = {
        'extend_existing': True,
    }
    id = Column(Integer, primary_key=True)
    name = Column(String(50))

执行Alembic命令时出现异常：

• 运行 alembic revision --autogenerate -m "first migrations"，报错 KeyError: 'spanner+spanner'
• 将URL改为 spanner:///... 后，报错 sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:spanner

但直接使用 spanner+spanner:///... 创建引擎并执行 python models.py 可成功建表，需解决Alembic适配Cloud Spanner的问题。

Alembic无法识别Cloud Spanner方言的核心原因是初始化时未自动加载sqlalchemy-spanner的插件，按以下步骤修复：

1. 统一数据库URL格式 #

将alembic.ini和main.py中的URL改为标准格式：

# alembic.ini
sqlalchemy.url = spanner:///projects/spanner-project/instances/spanner-instance/databases/spanner-database

# main.py
engine = create_engine(
    "spanner:///projects/spanner-project/instances/spanner-instance/databases/spanner-database"
)

2. 在env.py中显式注册Spanner方言 #

修改env.py，在开头添加方言注册代码，强制加载sqlalchemy-spanner插件：

# env.py 头部新增
from sqlalchemy_spanner import SpannerDialect
from sqlalchemy.dialects import registry
registry.register("spanner", "sqlalchemy_spanner", "SpannerDialect")

# 保留原有代码
from app.main import Base
target_metadata = Base.metadata

3. 重新执行Alembic命令 #

运行自动生成迁移的命令：

alembic revision --autogenerate -m "first migrations"

原理说明 #

sqlalchemy-spanner注册的方言名称为spanner，但Alembic初始化时未触发插件的自动注册逻辑。显式导入并注册方言后，Alembic可正确识别Cloud Spanner的连接格式。之前直接运行models.py能成功，是因为创建引擎时触发了sqlalchemy-spanner的导入，自动完成了方言注册。

内容的提问来源于stack exchange，提问作者Jeet Patel