Django 4.2集成Cassandra遇keyspace及连接注册错误求助

问题重现 #

升级至Django 4.2后，使用django-cassandra-engine集成Cassandra时出现两类核心错误：

1. 已在settings.py中配置keyspace，但仍抛出：

cassandra.cqlengine.CQLEngineException: Model keyspace is not set and no default is available. Set model keyspace or setup connection before attempting to generate a query.

2. 在模型中显式设置__keyspace__ = "my_keyspace"后，触发新错误：

Connection name '<object object at 0x7f4fb00d67a0>' doesn't exist in the registry.

环境信息：

• Python 3.10
• django-cassandra-engine 1.7.0
• Docker部署，Cassandra容器连通性已验证

解决思路 #

1. 检查DATABASES配置完整性 #

确保settings.py中的Cassandra数据库配置包含所有必填项，且配置DATABASE_ROUTERS指定路由：

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    },
    'cassandra': {
        'ENGINE': 'django_cassandra_engine',
        'NAME': 'my_keyspace',  # 对应Cassandra keyspace名称
        'USER': 'cassandra',
        'PASSWORD': 'cassandra',
        'HOST': 'cassandra-service',  # Docker服务名/容器IP，不要用localhost
        'PORT': 9042,
        'OPTIONS': {
            'connection': {
                'consistency': ConsistencyLevel.LOCAL_ONE,
                'retry_connect': True,
            }
        }
    }
}

# 强制Cassandra模型使用对应连接
DATABASE_ROUTERS = ['django_cassandra_engine.router.CassandraRouter']

未配置DATABASE_ROUTERS时，Django会默认使用default数据库连接，导致Cassandra模型无法识别keyspace。

2. 升级django-cassandra-engine版本 #

django-cassandra-engine 1.7.0发布于2022年，未完全适配Django 4.2。升级到最新稳定版修复兼容问题：

pip install --upgrade django-cassandra-engine

3. 模型显式关联连接别名 #

在模型中设置__keyspace__时，必须同时指定对应数据库连接的别名：

from django_cassandra_engine.models import DjangoCassandraModel

class Session(DjangoCassandraModel):
    __keyspace__ = 'my_keyspace'
    __connection__ = 'cassandra'  # 对应settings.py中DATABASES的键名
    # 字段定义
    session_id = columns.UUID(primary_key=True)
    created_at = columns.DateTime()

缺少__connection__指定时，cqlengine无法找到注册的连接实例，会抛出连接名称不存在的错误。

4. 确保连接初始化时机正确 #

如果在Django启动前执行查询（如脚本、异步视图），需手动初始化Cassandra连接：

from cassandra.cqlengine import connection
from django.conf import settings

def fetch_sessions_list(ux_vms):
    # 仅在未初始化时执行连接
    if not connection._connections:
        connection.setup(
            hosts=[settings.DATABASES['cassandra']['HOST']],
            default_keyspace=settings.DATABASES['cassandra']['NAME'],
            username=settings.DATABASES['cassandra']['USER'],
            password=settings.DATABASES['cassandra']['PASSWORD']
        )
    # 执行查询逻辑
    sessions_db = Session.objects.all()
    # ...后续处理

5. 排查Docker环境细节 #

• 确认Cassandra容器的9042端口未被占用，且端口映射正确
• 验证my_keyspace已在Cassandra中创建，且当前用户拥有读写权限
• 检查settings.py中的HOST为Docker服务名（Compose场景）或容器IP，避免用localhost

内容的提问来源于stack exchange，提问作者Usman Rafiq