Solución de problemas de mssql-django

Diagnostique y resuelva problemas comunes con el mssql-django back-end para SQL Server, Azure SQL Database, Azure SQL Managed Instance y la base de datos SQL en Microsoft Fabric.

mssql-django La versión 2.0 soporta la ruta predeterminada de controlador pyodbc y una ruta de controlador mssql-python con opción de activación. Para más información, consulte Seleccionar el controlador de base de datos para mssql-django.

Problemas de conexión

En esta sección se tratan los errores de conexión más comunes y cómo resolverlos.

No se encontró el controlador ODBC en la ruta de pyodbc

Síntomas:

django.core.exceptions.ImproperlyConfigured: 'ODBC Driver 18 for SQL Server' is not a recognized ODBC driver

O bien:

Error: ('01000', "[01000] [unixODBC][Driver Manager]Can't open lib 'ODBC Driver 18 for SQL Server'")

Posibles causas y soluciones:

El controlador ODBC no está instalado

Instala el controlador Microsoft ODBC para SQL Server cuando uses la ruta pyodbc predeterminada. Para obtener vínculos de descarga, consulte Descargar ODBC Driver for SQL Server. La ruta mssql-python no utiliza un controlador ODBC instalado externamente.

Varias versiones de controlador instaladas

Especifique el nombre o la ruta exactos del controlador en settings.py:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<database>",
        "USER": "<user_id>",
        "PASSWORD": "<password>",
        "HOST": "<server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 17 for SQL Server",
        },
    },
}

En Linux, especifique la ruta de acceso completa:

"OPTIONS": {
    "driver": "/opt/microsoft/msodbcsql17/lib64/libmsodbcsql-17.10.so.6.1",
},

Comprobación de los controladores instalados
- En Linux/macOS, ejecute odbcinst -q -d.
- En Windows, compruebe orígenes de datos ODBC en Herramientas administrativas.

MSSQL-Python rechaza una opción de conexión

Síntomas:

Un alias que se establece en "python_driver": "mssql_python" da error durante la configuración de la conexión después de mover las palabras clave de la cadena de conexión de pyodbc a OPTIONS["extra_params"], con uno de estos errores:

mssql_python.exceptions.ConnectionStringParseError: Connection string parsing failed:
  Unknown keyword 'longasmax' is not recognized

mssql_python.exceptions.ConnectionStringParseError: Connection string parsing failed:
  Reserved keyword 'driver' is controlled by the driver and cannot be specified by the user

El nombre de la palabra clave en el mensaje está en minúsculas, así que una palabra clave que escribiste aparece LongAsMax como longasmax. ConnectionStringParseError no forma parte de la jerarquía de excepciones de DB-API, así que Django no lo vuelve a encapsular como error django.db.utils.

Posibles causas y soluciones:

Palabra clave exclusiva de pyodbc en extra_params

La ruta mssql-python valida extra_params con una lista de elementos permitidos. DRIVER y APP están reservados para el conductor y producen el Reserved keyword formulario. DSN, SERVERNAME, MARS_Connection y palabras clave exclusivas de pyodbc como LongAsMax, ColumnEncryption, WSID, AnsiNPW, QuotedId, Regional, UseFMTONLY, Network Library, Description, Current Language y Connect Timeout no están en la lista de permitidos y generan la forma Unknown keyword. Elimina la palabra clave o usa la ruta pyodbc por defecto para un alias que necesite esa opción ODBC.
Se espera que la opción del controlador controle mssql-python

La ruta mssql-python ignora driver, dsn, host_is_server, y unicode_results. HOST y PORT se convierten SERVER=<server>,<port>en , y un vacío HOST se convierte localhosten .

La dependencia de MSSQL-Python es demasiado antigua

Síntomas:

Un alias que establece "python_driver": "mssql_python" falla durante la configuración de la conexión con uno de estos errores:

django.core.exceptions.ImproperlyConfigured: mssql-python 1.15.0 or newer is required; you have 1.14.0

django.core.exceptions.ImproperlyConfigured: The 'python_driver' connection option requests mssql-python, but the module could not be imported: No module named 'mssql_python'. Install it with 'pip install "mssql-python>=1.15.0"'.

El segundo formulario significa que el mssql_python módulo no es importable en absoluto.

Solución: Instalar mssql-python>=1.15.0. mssql-django La versión 2.0 declara mssql-python>=1.15.0, por lo que una normal pip install mssql-django resuelve una versión compatible en plataformas compatibles.

La alternativa del controlador 17 no se aplica a mssql-python

Síntomas:

Un alias que establece "python_driver": "mssql_python" sigue sin funcionar aunque Microsoft ODBC Driver 17 for SQL Server está instalado.

No hay ningún error distintivo en este caso. La ruta mssql-python ignora la driver opción en silencio, por lo que la conexión falla con el error subyacente que se aplique. Si en su lugar mueves el nombre del controlador a extra_params, obtienes un error de Reserved keyword 'driver'. Ver mssql-python rechaza una opción de conexión.

Solución: Usar la ruta pyodbc predeterminada si el alias debe usar un controlador ODBC 17 instalado externamente. La ruta mssql-python no vuelve al controlador 17 y ignora esa driver opción. Esa ruta no necesita un controlador ODBC instalado por separado.

Conexión rechazada

Síntomas:

django.db.utils.OperationalError: ('08001', '[08001] ... TCP Provider: Error code 0x2749 ...')

Posibles causas y soluciones:

TCP/IP no habilitado en SQL Server
- Abra el Administrador de configuración de SQL Server.
- En SQL Server Configuración de red, habilite TCP/IP.
- En Propiedades tcp/IP, active la dirección IP usada para la conexión.
- Reinicie el servicio SQL Server.
Puerto de bloqueo del firewall 1433
- Compruebe que las reglas de firewall permiten conexiones entrantes en el puerto 1433.
- Para Azure SQL, agregue la dirección IP del cliente en la configuración del firewall del portal de Azure.
Nombre o puerto incorrectos del servidor

Compruebe los valores de HOST y PORT en su configuración.

Síntomas:

django.db.utils.OperationalError: ('28000', "[28000] [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Login failed for user '<user_id>'. (18456) (SQLDriverConnect); [28000] [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Login failed for user '<user_id>'. (18456)")

Sobre la ruta mssql-python:

django.db.utils.OperationalError: Driver Error: Invalid authorization specification; DDBC Error: [Microsoft][SQL Server]Login failed for user '<user_id>'.

Posibles causas y soluciones:

Credenciales incorrectas

Compruebe el nombre de usuario y la contraseña.
La base de datos en NAME no existe

En SQL Server, la ruta mssql-python genera el mismo OperationalError mensaje que una contraseña incorrecta, así que el mensaje por sí solo no te dice cuál has tocado. Confirma que la base de datos existe antes de cambiar las credenciales. Dirige NAME a master para probar el inicio de sesión por separado: si conecta, las credenciales son correctas y el problema está en la base de datos. La ruta pyodbc informa este caso por separado como Cannot open database "<database>" requested by the login. The login failed. (4060).

Azure SQL Database informa de este caso de forma diferente. La ruta de mssql-python genera Driver Error: General error; DDBC Error: [Microsoft][SQL Server]Cannot open server "<server>" requested by the login. The login failed. El mensaje menciona el servidor, pero el nombre del servidor es correcto. Mejor comproba NAME .
El usuario no existe

Confirme que el inicio de sesión está asignado a un usuario de la base de datos de destino.
autenticación de SQL Server deshabilitada

Habilite la autenticación en modo mixto o use la autenticación de Windows o la autenticación de Microsoft Entra.

Tiempo de espera de conexión

Síntomas:

django.db.utils.OperationalError: ('HYT00', '[HYT00] [Microsoft][ODBC Driver 18 for SQL Server]Login timeout expired')

Posibles causas y soluciones:

Latencia de red

Aumente connection_timeout en OPCIONES.
Azure SQL Database sin servidor con la pausa automática habilitada

Una base de datos en pausa automática se reanuda en el primer intento de conexión, y ese intento puede fallar con el error 40613 mientras la base de datos se reanuda. Ponlo connection_timeout al menos a 60 y vuelve a intentar la primera conexión. Para más información, consulta Azure SQL Database sin servidor y Pausa automática y reanudación automática.

Servidor sobrecargado

Aumente connection_retries y connection_retry_backoff_time.

"OPTIONS": {
    "driver": "ODBC Driver 18 for SQL Server",
    "connection_timeout": 30,
    "connection_retries": 5,
    "connection_retry_backoff_time": 10,
},

Problemas de migración

Estos errores se producen durante las operaciones de migración de Django en SQL Server.

Problemas de SQL en bruto y GROUP BY

Estos errores se producen cuando consultas sin procesar o anotadas con una cláusula GROUP BY pasan por el proceso de reescritura de marcadores de posición del backend.

`IndexError` en GROUP BY con `%%` parámetros escapados y reales

Síntomas:

IndexError: Replacement index N out of range for positional args tuple

La consulta funciona sin la cláusula GROUP BY y sin el literal con escape %%, pero falla cuando ambos están presentes junto a un parámetro real %s.

Solución: Actualizar a una versión actual mssql-django . El backend restringe la expresión regular de reescritura de marcadores de posición únicamente a %% y %s, de modo que los literales %% escapados se conservan intactos y no se inyectan marcadores de posición fantasma.

`NotImplementedError` para `IntegerChoices` en consultas GROUP BY en bruto

Síntomas:

NotImplementedError: Not supported type <enum '...'> (StatusChoices.IN_PROGRESS)

El mismo valor de enum funciona en consultas ORM y en consultas en bruto sin GROUP BY, pero falla cuando se pasa como parámetro a una consulta en bruto que contiene una GROUP BY cláusula.

Solución: Actualizar a una versión actual mssql-django . El backend utiliza isinstance para las comprobaciones de tipo de parámetros en la ruta GROUP BY, por lo que IntegerChoices (una subclase de int) se enlaza correctamente. bool sigue vinculando bit, y int simple no cambia.

Problemas con la búsqueda de expresiones regulares

`regex` o `iregex` no devuelve filas

Síntomas: La consulta se ejecuta sin error y devuelve un conjunto de resultados vacío, aunque las filas coincidan con el patrón.

Product.objects.filter(name__regex=r"^Widget \d+$")  # no rows, though "Widget 42" exists

Causa: dbo.REGEXP_LIKE ignora el espacio en blanco literal en el patrón. El patrón se empareja como si fuera ^Widget\d+$, lo cual ningún valor que contiene un espacio puede satisfacer. No surge nada, así que el resultado vacío parece un problema de datos.

Solución: Escribe espacios en blanco como escape o clase de carácter:

Product.objects.filter(name__regex=r"^Widget\s\d+$")
Product.objects.filter(name__regex=r"^Widget[ ]\d+$")

`Cannot find ... dbo.REGEXP_LIKE`

Síntomas:

django.db.utils.ProgrammingError: ('42000', '[42000] [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Cannot find either column "dbo" or the user-defined function or aggregate "dbo.REGEXP_LIKE", or the name is ambiguous. (4121) (SQLExecDirectW)')

En la ruta mssql-python:

django.db.utils.ProgrammingError: Driver Error: Syntax error or access violation; DDBC Error: [Microsoft][SQL Server]Cannot find either column "dbo" or the user-defined function or aggregate "dbo.REGEXP_LIKE", or the name is ambiguous.

Causa: El ensamblador CLR no está instalado en la base de datos que consultas. Se instala por base de datos, no por servidor.

Solución: Ejecuta python manage.py install_regex_clr <database> contra esa base de datos. Vuelva a ejecutarlo después de eliminar y volver a crear una base de datos. Consulta Configurar consultas de regex.

Problemas de fecha y hora

`Now()` los valores se desplazan cuando `USE_TZ=True`

Síntomas:

Las marcas de tiempo escritas con Django Now(), auto_nowo auto_now_add se desplazan cuando la zona horaria del host de SQL Server no es UTC.

Solución: Actualizar a una versión actual mssql-django . El backend genera SQL compatible con zonas horarias Now(), conserva los desplazamientos de datetimeoffset y lee datos de zona horaria a través de zoneinfo y tzdata.

`AttributeError` al llamar a `.explain()`

Síntomas:

AttributeError: ... explain_format ...

Solución: Actualizar a una versión actual mssql-django . Los encargos de backend explican los metadatos de cada versión compatible con Django.

No se puede modificar AutoField

Síntomas:

django.db.utils.ProgrammingError: Cannot alter column to or from an IDENTITY column

Solución: SQL Server no admite la modificación de un campo desde o hacia AutoField. Cree un nuevo modelo con el tipo de campo deseado, migre los datos manualmente y, a continuación, quite la tabla anterior. Para obtener soluciones alternativas, consulte Migraciones de base de datos con mssql-django.

Error en el cambio de nombre debido a una restricción de clave externa

Síntomas:

django.db.utils.ProgrammingError: ... could not drop constraint ...

Solución: SQL Server requiere quitar restricciones de clave externa antes de cambiar el nombre de las columnas. Use SeparateDatabaseAndState en la migración. Para obtener un ejemplo, consulte Migraciones de base de datos con mssql-django.

Problemas de codificación

Los errores de codificación suelen ocurrir en la ruta pyodbc cuando pyodbc se malinterpretan los datos de caracteres de SQL Server.

Errores de codificación Unicode

Síntomas:

UnicodeDecodeError: 'utf-8' codec can't decode byte ...

Solución: Configure la codificación pyodbc en el diccionario OPTIONS. La ruta mssql-python ignora unicode_results.

"OPTIONS": {
    "driver": "ODBC Driver 18 for SQL Server",
    "unicode_results": True,
},

Problemas de FreeTDS

FreeTDS requiere una configuración específica de pyodbc que difiera del controlador ODBC de Microsoft.

Error host_is_server

Síntomas:

Se produce un error en la conexión cuando se usa FreeTDS sin especificar host_is_server.

Solución: establézcalo host_is_server en True cuando use FreeTDS:

"OPTIONS": {
    "driver": "FreeTDS",
    "host_is_server": True,
},

Para obtener más información sobre la configuración de FreeTDS, consulte Opciones de conexión para mssql-django.

Prueba de problemas de base de datos

La creación y destrucción de la base de datos de prueba pueden producir errores en función del método de autenticación.

No se puede crear una base de datos de prueba con identidad administrada

Síntomas:

django.db.utils.DatabaseError: ('42000', '[42000] ... EXECUTE permission denied on object ...')

O bien:

django.db.utils.OperationalError: ('28000', ... login failed ...)

El ejecutor de pruebas no puede crear ni eliminar la base de datos de prueba cuando se usa la autenticación de identidad administrada (ActiveDirectoryMsi). Esta limitación existe porque:

Las credenciales de identidad administrada se obtienen del entorno de host (como Azure vm y App Service).
El ejecutor de pruebas intenta conectarse con las credenciales de la base de datos test durante la fase de desmontaje.
A una identidad administrada se le pueden conceder roles de nivel de base de datos, pero la creación y eliminación de bases de datos de prueba suelen requerir permisos de nivel de servidor que los ejecutores de pruebas a menudo no tienen.

Métodos de autenticación afectados:

ActiveDirectoryMsi (identidad administrada de Azure)
ActiveDirectoryServicePrincipal (cuando se configura solo en el ámbito del servidor)

Métodos de autenticación admitidos (la creación de bases de datos de prueba funciona):

ActiveDirectoryPassword
ActiveDirectoryIntegrated
Autenticación de SQL (nombre de usuario y contraseña)

Ventajas y desventajas de la autenticación para entornos de prueba

Método	Sin secretos	Funciona con la creación o eliminación automática de la base de datos de prueba	Uso típico
`ActiveDirectoryMsi`	Yes	Normalmente no (a menos que se concedan derechos de nivel de servidor)	cargas de trabajo de producción alojadas en Azure
`ActiveDirectoryServicePrincipal`	No (secreto de cliente/certificado)	Depende de los derechos de nivel de servidor concedidos	CI/CD con administración de identidades explícita
`ActiveDirectoryPassword`	No	Sí (con permisos de SQL suficientes)	Entornos de CI controlados y para desarrolladores
Autenticación de SQL	No	Sí (con permisos de SQL suficientes)	Entornos de prueba locales o aislados

Soluciones:

Para desarrollo: usa la marca --keepdb para omitir el desmontaje de la base de datos de pruebas:
```
python manage.py test --keepdb
```

Para canalizaciones de CI/CD: cree previamente una base de datos de prueba dedicada y conceda a la identidad administrada CREATE TABLE y ALTER los permisos:

-- Connect as a server admin, then:
USE [test_database_name];

-- Grant permissions for managed identity (replace with your identity name)
CREATE USER [your-app-identity] FROM EXTERNAL PROVIDER;
GRANT CREATE TABLE TO [your-app-identity];
GRANT ALTER ON SCHEMA::dbo TO [your-app-identity];

Alternativa: use la autenticación de SQL para entornos de prueba o cambie a ActiveDirectoryPassword para los ejecutores de pruebas de CI/CD.

Procedimientos de reversión

Si una migración falla a mitad del proceso, utilice esta secuencia de reversión para volver a un estado válido conocido:

Detenga las operaciones de escritura de la aplicación para evitar una mayor desviación del esquema.

Inspección del estado de migración:

python manage.py showmigrations
python manage.py sqlmigrate <app_label> <migration_number>

Revierte a la última migración que se sabe que funcionaba correctamente:
```
python manage.py migrate <app_label> <previous_migration>
```
Si el historial de esquemas y la migración difieren, repare el estado cuidadosamente con --fake solo después de comprobar el esquema real de la base de datos.
Vuelva a ejecutar las migraciones primero en un entorno de pruebas y, después, vuelva a intentarlo en producción.

Importante

En el caso de migraciones destructivas, como cambios de eliminación, cambio de nombre y tipo de columna, realice una copia de seguridad probada antes de la implementación. Si la reversión por migración no es posible, restaure desde la copia de seguridad y vuelva a aplicar las migraciones validadas.

Problemas de Docker y contenedor

Las imágenes de contenedor requieren la instalación explícita de controladores ODBC y dependencias de compilación al usar la ruta predeterminada de pyodbc. La ruta mssql-python no tiene una instalación separada de drivers ODBC, pero aún necesita el runtime unixODBC, porque el backend importa pyodbc cuando Django lo carga.

No se encontró el controlador ODBC en el contenedor

Síntomas:

Error: ('01000', "[01000] [unixODBC][Driver Manager]Can't open lib 'ODBC Driver 18 for SQL Server'")

Posibles causas y soluciones:

Controlador ODBC no instalado en la imagen de contenedor

Las imágenes base Slim o Alpine no incluyen el controlador ODBC. Añade el repositorio APT de Microsoft e instala msodbcsql18 en el archivo Dockerfile cuando uses pyodbc. Consulte Implementación en App Service para obtener un ejemplo completo de Dockerfile.
Falta unixodbc-dev el paquete

La rueda pyodbc está vinculada a libodbc.so. Instale unixodbc-dev (Debian/Ubuntu) o unixODBC-devel (RHEL/Fedora) antes de instalar paquetes Python.
apt-get autoremove Eliminado libgssapi-krb5-2 tras la instalación del controlador

msodbcsql18 se carga libgssapi-krb5-2 en tiempo de ejecución sin declararlo como una dependencia. La biblioteca suele aparecer como una dependencia de curl, por lo que purgar curl con --auto-remove, o ejecutarse apt-get autoremove después, la elimina. La imagen se compila correctamente, pero después fallan todas las conexiones. Instala libgssapi-krb5-2 expresamente y no realices la eliminación automática tras instalar el controlador.

Se informó de que faltaba el controlador 17 cuando instalaste la versión 18

Síntomas:

Error: ('01000', "[01000] [unixODBC][Driver Manager]Can't open lib 'ODBC Driver 17 for SQL Server' : file not found (0) (SQLDriverConnect)")

El error nombra la versión 17, pero odbcinst -q -d muestra la versión 18 registrada y dpkg -l msodbcsql18 la muestra instalada.

Causa: La versión 18 está registrada pero no se carga, así que mssql-django vuelve a la versión 17, que no está instalada. El mecanismo alternativo informa del segundo controlador que intentó, no del que falló.

Solución: instalar libgssapi-krb5-2 y reconstruir. Consulta la nota anterior de eliminación automática para ver cómo desaparece la biblioteca.

Error de carga del módulo pyodbc en un contenedor

Síntomas:

django.core.exceptions.ImproperlyConfigured: Error loading pyodbc module: libodbc.so.2: cannot open shared object file: No such file or directory

Causa: La imagen no tiene el entorno de ejecución de unixODBC. mssql-django importa pyodbc cuando Django carga el backend, así que este error ocurre también en la ruta mssql-python, antes de que se intente cualquier conexión.

Solución: Instalar unixodbc (o unixodbc-dev).

El controlador MSSQL-Python no se carga

Síntomas:

django.db.utils.OperationalError: Driver Error: Connection operation failed; DDBC Error: Failed to load the driver.

Causa: El controlador que se incluye con mssql-python necesita las bibliotecas de ejecución de Kerberos, que las imágenes base slim no incluyen.

Solución: Instalar libkrb5-3 y libgssapi-krb5-2.

pyodbc no se compila en imágenes slim

Síntomas:

error: command 'gcc' failed: No such file or directory

O bien:

fatal error: sql.h: No such file or directory

Solución: Instale las dependencias de compilación antes de pip install:

RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    g++ \
    unixodbc-dev

Como alternativa, utiliza una compilación multietapa para reducir el tamaño de la imagen final:

# Build stage
FROM python:3.12-slim AS builder
RUN apt-get update && apt-get install -y --no-install-recommends gcc g++ unixodbc-dev
COPY requirements.txt .
RUN pip wheel --no-cache-dir --wheel-dir /wheels -r requirements.txt

# Runtime stage
FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl gnupg2 unixodbc \
    && curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg \
    && curl -fsSL https://packages.microsoft.com/config/debian/12/prod.list > /etc/apt/sources.list.d/mssql-release.list \
    && apt-get update \
    && ACCEPT_EULA=Y apt-get install -y --no-install-recommends msodbcsql18 libgssapi-krb5-2 \
    && apt-get purge -y curl gnupg2 \
    && rm -rf /var/lib/apt/lists/*
COPY --from=builder /wheels /wheels
RUN pip install --no-cache-dir /wheels/*

El contenedor no se puede conectar a SQL Server

Síntomas:

django.db.utils.OperationalError: ('08001', '... TCP Provider: Error code 0x2749 ...')

Posibles causas y soluciones:

El nombre del servicio Docker Compose no se usa como host

Al usar Docker Compose, establezca DB_HOST en el nombre del servicio (por ejemplo, db), no localhost o 127.0.0.1.

SQL Server contenedor no listo

El contenedor de SQL Server tarda varios segundos en iniciarse. Agregue una comprobación de estado o un retraso de inicio:

services:
  db:
    image: mcr.microsoft.com/mssql/server:2022-latest
    healthcheck:
      test: /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$$MSSQL_SA_PASSWORD" -No -Q "SELECT 1" || exit 1
      # $$ escapes the $ sign in Docker Compose YAML
      interval: 10s
      retries: 10
      start_period: 10s
  web:
    depends_on:
      db:
        condition: service_healthy

Conflictos de asignación de puertos

Si otra instancia de SQL Server se ejecuta en el host, cambie el puerto expuesto (por ejemplo, 1434:1433) y actualice la configuración de Django en consecuencia.

Azure SQL recuperación de errores transitorios

El mssql-django backend detecta automáticamente las conexiones de Azure SQL Database y Azure SQL Managed Instance consultando SERVERPROPERTY('EngineEdition'). Cuando se ejecuta en Azure SQL, el back-end reintenta las conexiones en errores transitorios (como límites de recursos temporales o interrupciones breves de red).

Puede ajustar este comportamiento con las connection_retries opciones y connection_retry_backoff_time :

"OPTIONS": {
    "driver": "ODBC Driver 18 for SQL Server",
    "connection_retries": 5,
    "connection_retry_backoff_time": 5,
},

Esta configuración solo se aplica al establecimiento de conexión inicial. El back-end no reintenta las consultas con errores. Si se produce un error transitorio en una consulta después de establecer la conexión, la excepción se propaga al código de la aplicación. Use la lógica de reintento de nivel de aplicación (por ejemplo, django-retry-db o un middleware personalizado) para la resistencia de nivel de consulta.

Consultas lentas y regresiones de planes

Estos problemas suelen requerir análisis del lado del servidor junto con una revisión de las consultas a nivel de Django.

La consulta se ralentiza o empieza a agotar el tiempo de espera

Síntomas:

El mismo conjunto de consultas se ralentiza con el tiempo o empieza a agotar el tiempo de espera tras una implementación, un cambio de índice o una actualización de estadísticas.

Posibles causas y soluciones:

Empezar con informes de rendimiento integrados

Para SQL Server y Azure SQL Managed Instance, abra Panel de rendimiento en SQL Server Management Studio. Para Azure SQL Database, abra Información de rendimiento de consultas para Azure SQL Database. Estas herramientas suelen ser un mejor primer paso que las consultas ad hoc a las DMV porque permiten identificar rápidamente las consultas costosas, las esperas y la presión sobre los recursos.
Regresión del plan

Use Almacén de consultas para encontrar la consulta lenta y comprobar si tiene varios planes. Empiece por las vistas Consultas con regresión y Consultas con mayor consumo de recursos que se describen en Prácticas recomendadas para supervisar cargas de trabajo con Almacén de consultas.
Plan de ejecución ineficaz

Abre un plan de ejecución real para la instrucción y comprueba si hay escaneos de tablas o índices, búsquedas de claves grandes, desbordamientos de hash o estimaciones de filas inexactas. Para más información, consulte Información general sobre el plan de ejecución.
Se ha identificado un cuello de botella incorrecto

Si la consulta no está limitada por la CPU, use las estadísticas de espera de Almacén de consultas y Identifique cuellos de botella para distinguir entre limitaciones de CPU, memoria, E/S de disco, bloqueos y presión sobre las conexiones.
Corrección aplicada en la capa incorrecta

Aplique la solución más pequeña que resulte eficaz: añada o ajuste índices, actualice estadísticas, reduzca el número de columnas y filas seleccionadas o agrupe en lotes las operaciones de escritura de gran volumen. Si necesita una mitigación de emergencia, un DBA puede forzar temporalmente en Almacén de consultas un plan previamente validado mientras corrige la causa raíz.

Uso de dbshell para consultas interactivas

El comando de administración de dbshell Django abre un shell de SQL interactivo conectado a la base de datos:

python manage.py dbshell

El back-end usa sqlcmd al configurar el controlador ODBC de Microsoft o isql cuando se usa FreeTDS. Compruebe que la herramienta se encuentra en su PATH:

Windows: sqlcmd se incluye con herramientas de SQL Server o puede descargarla por separado.
Linux y macOS: instale mssql-tools18 desde el repositorio de Microsoft.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-09-29

Solución de problemas de mssql-django

Problemas de conexión

No se encontró el controlador ODBC en la ruta de pyodbc

MSSQL-Python rechaza una opción de conexión

La dependencia de MSSQL-Python es demasiado antigua

La alternativa del controlador 17 no se aplica a mssql-python

Conexión rechazada

Error de inicio de sesión

Tiempo de espera de conexión

Problemas de migración

Problemas de SQL en bruto y GROUP BY

IndexError en GROUP BY con %% parámetros escapados y reales

NotImplementedError para IntegerChoices en consultas GROUP BY en bruto

Problemas con la búsqueda de expresiones regulares

__regex o __iregex no devuelve filas

Cannot find ... dbo.REGEXP_LIKE

Problemas de fecha y hora

Now() los valores se desplazan cuando USE_TZ=True

AttributeError al llamar a .explain()

No se puede modificar AutoField

Error en el cambio de nombre debido a una restricción de clave externa

Problemas de codificación

Errores de codificación Unicode

Problemas de FreeTDS

Error host_is_server

Prueba de problemas de base de datos

No se puede crear una base de datos de prueba con identidad administrada

Ventajas y desventajas de la autenticación para entornos de prueba

Procedimientos de reversión

Problemas de Docker y contenedor

No se encontró el controlador ODBC en el contenedor

Se informó de que faltaba el controlador 17 cuando instalaste la versión 18

Error de carga del módulo pyodbc en un contenedor

El controlador MSSQL-Python no se carga

pyodbc no se compila en imágenes slim

El contenedor no se puede conectar a SQL Server

Azure SQL recuperación de errores transitorios

Consultas lentas y regresiones de planes

La consulta se ralentiza o empieza a agotar el tiempo de espera

Uso de dbshell para consultas interactivas

Contenido relacionado

Comentarios

Recursos adicionales

`IndexError` en GROUP BY con `%%` parámetros escapados y reales

`NotImplementedError` para `IntegerChoices` en consultas GROUP BY en bruto

`regex` o `iregex` no devuelve filas

`Cannot find ... dbo.REGEXP_LIKE`

`Now()` los valores se desplazan cuando `USE_TZ=True`

`AttributeError` al llamar a `.explain()`