使用服务主体认证连接Azure SQL时Django遇MigrationSchemaMissing异常

问题场景 #

使用Microsoft官方mssql-django包，通过服务主体认证连接Azure SQL数据库，数据库配置如下：

DATABASES = {
    'default': {
        'ENGINE': 'mssql',
        'NAME': <db_name>,  
        'USER': <db_user>,
        'PASSWORD': <db_password>,
        'HOST': "<url>.database.windows.net",
        'PORT': '1433',
        'OPTIONS': {
            'driver': 'ODBC Driver 17 for SQL Server',
            'connection_timeout':60,
            'connection_retries':3,
            "extra_params": "Authentication=ActiveDirectoryServicePrincipal",
        },
    }
}

执行python manage.py migrate时触发如下错误：

raise MigrationSchemaMissing(
django.db.migrations.exceptions.MigrationSchemaMissing: Unable to create the django_migrations table (('42000', '[42000] [Microsoft][ODBC Driver 17 for SQL Server][SQL Server]The specified schema name "<db_user>@<azure_tenant_id>" either does not exist or you do not have permission to use it. (2760) (SQLExecDirectW)'))

排查结论 #

• 手动登录数据库不指定Schema创建表时同样报权限错误，确认服务主体认证后未获取到默认Schema
• 执行SELECT SCHEMA_NAME()返回null，说明当前用户未分配默认Schema；migrate时自动尝试使用<db_user>@<azure_tenant_id>作为Schema，但SQL Server不支持包含@的Schema名称，且该Schema本身不存在

解决方案 #

1. 为服务主体用户指定默认Schema #

使用Azure SQL的管理员账号登录数据库，执行以下SQL：

-- 查看用户当前默认Schema
SELECT name, default_schema FROM sys.database_principals WHERE name = '<db_user>';

-- 若default_schema为NULL，设置默认Schema（以dbo为例，也可使用自定义Schema）
ALTER USER <db_user> WITH DEFAULT_SCHEMA = dbo;

2. 授予用户对应Schema的权限 #

确保用户拥有在指定Schema下创建表、执行迁移的权限：

GRANT ALTER, CREATE TABLE, CREATE PROCEDURE ON SCHEMA::dbo TO <db_user>;

3. 验证并重新执行迁移 #

• 重新连接数据库，执行SELECT SCHEMA_NAME()，确认返回设置的默认Schema（如dbo）
• 再次运行python manage.py migrate即可正常执行

内容的提问来源于stack exchange，提问作者Aashay Amballi