Solucionar problemas de mssql-django

Diagnostique e resolva problemas comuns no mssql-django back-end do SQL Server, do Banco de Dados SQL do Azure, da Instância Gerenciada de SQL do Azure e do Banco de Dados SQL no Microsoft Fabric.

mssql-django 2.0 suporta o caminho padrão do driver pyodbc e um caminho opcional do driver mssql-python. Para mais informações, veja Selecionar o driver de banco de dados para mssql-django.

Problemas de conexão

Esta seção aborda os erros de conexão mais comuns e como resolvê-los.

O driver ODBC não foi encontrado no caminho do pyodbc

Sintomas:

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

Ou:

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

Possíveis causas e soluções:

• Driver ODBC não instalado

  Instale o Driver ODBC da Microsoft para SQL Server ao usar o caminho padrão do pyodbc. Para obter links de download, consulte Baixar o Driver ODBC para SQL Server. O caminho mssql-python não usa um driver ODBC instalado externamente.

• Várias versões do driver instaladas

  Especifique o nome ou caminho exato do driver em 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",
          },
      },
  }
  

  No Linux, especifique o caminho completo:

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

• Verificar drivers instalados

  • No Linux/macOS, execute odbcinst -q -d.
  • Em Windows, verifique as fontes de dados ODBC nas Ferramentas Administrativas.

MSSQL-Python rejeita uma opção de conexão

Sintomas:

Um alias que define "python_driver": "mssql_python" falha durante o estabelecimento da conexão após você mover as palavras-chave da string de conexão do pyodbc para OPTIONS["extra_params"], com um destes erros:

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

O nome da palavra-chave na mensagem é convertido para minúsculas, então uma palavra-chave que você escreveu como LongAsMax aparece como longasmax. ConnectionStringParseError não faz parte da hierarquia de exceções da DB-API, então o Django não o encapsula novamente como um erro django.db.utils.

Possíveis causas e soluções:

• Palavra-chave somente para pyodbc em extra_params

  O caminho mssql-python valida extra_params em relação a uma lista de itens permitidos. DRIVER e APP são reservados para o motorista e produzem o formulário Reserved keyword. DSN, SERVERNAME, MARS_Connection e palavras-chave exclusivas do pyodbc, como LongAsMax, ColumnEncryption, WSID, AnsiNPW, QuotedId, Regional, UseFMTONLY, Current Language, Network Library, Description e Connect Timeout, não estão na lista de permissões e produzem o formulário Unknown keyword. Remova a palavra-chave ou use o caminho padrão pyodbc para um alias que precise dessa opção ODBC.

• Opção de driver esperada para controlar mssql-python

  O caminho mssql-python ignora driver, dsn, host_is_server, e unicode_results. HOST e PORT se tornam SERVER=<server>,<port>, e um HOST vazio se torna localhost.

A dependência MSSQL-Python é muito antiga

Sintomas:

Um alias que ativa "python_driver": "mssql_python" falha na configuração da conexão com um desses erros:

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"'.

O segundo formulário significa que o mssql_python módulo não é importável de forma alguma.

Solução: Instalar mssql-python>=1.15.0. mssql-django A versão 2.0 declara mssql-python>=1.15.0, então um normal pip install mssql-django resolve uma versão compatível nas plataformas suportadas.

A alternativa do Driver 17 não se aplica ao mssql-python

Sintomas:

Um alias que se configura "python_driver": "mssql_python" ainda falha mesmo com o driver Microsoft ODBC 17 para SQL Server instalado.

Não há erro distinto para este caso. A implementação mssql-python ignora silenciosamente a opção driver, de modo que a conexão falha com o erro subjacente que for aplicável. Se você mover o nome do motorista para extra_params em vez disso, gerará um erro Reserved keyword 'driver'. Consulte a rejeição de uma opção de conexão pelo mssql-python.

Solução: Use o caminho padrão pyodbc se o alias precisar usar um Driver ODBC 17 instalado externamente. O caminho mssql-python não volta para o Driver 17, e ele ignora essa driver opção. Esse caminho não precisa de um driver ODBC instalado separadamente.

Conexão recusada

Sintomas:

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

Possíveis causas e soluções:

• TCP/IP não habilitado no SQL Server

  • Abra o SQL Server Configuration Manager.
  • Em SQL Server Configuração de Rede, habilite TCP/IP.
  • Em Propriedades TCP/IP, ative o endereço IP usado para a conexão.
  • Reinicie o serviço SQL Server.

• Firewall bloqueando a porta 1433

  • Verifique se as regras de firewall permitem conexões de entrada na porta 1433.
  • Para SQL do Azure, adicione o IP do cliente nas configurações de firewall do portal Azure.

• Nome ou porta do servidor incorreto

  Verifique os valores HOST e PORT em sua configuração.

Falha no logon

Sintomas:

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)")

No caminho do mssql-python:

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

Possíveis causas e soluções:

• Credenciais incorretas

  Verifique o nome de usuário e a senha.

• O banco de dados em NAME não existe

  No SQL Server, o caminho mssql-python gera a mesma OperationalError mensagem com a mesma mensagem que uma senha ruim, então a mensagem sozinha não diz qual você atingiu. Confirme que o banco de dados existe antes de mudar as credenciais. Aponte NAME para master para testar o acesso isoladamente: se conectar, as credenciais estão corretas e o problema está no banco de dados. O caminho pyodbc reporta esse caso separadamente como Cannot open database "<database>" requested by the login. The login failed. (4060).

  Banco de Dados SQL do Azure relata esse caso de forma diferente. O caminho mssql-python gera Driver Error: General error; DDBC Error: [Microsoft][SQL Server]Cannot open server "<server>" requested by the login. The login failed. A mensagem menciona o servidor, mas o nome do servidor está correto. Confira NAME em vez disso.

• O usuário não existe

  Confirme se o logon foi mapeado para um usuário no banco de dados de destino.

• SQL Server autenticação desabilitada

  Habilite a autenticação de modo misto ou use a autenticação do Windows ou a autenticação do Microsoft Entra.

Tempo de espera da conexão esgotado

Sintomas:

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

Possíveis causas e soluções:

• Latência da rede

  Aumentar connection_timeout em OPÇÕES.

• Banco de Dados SQL do Azure serverless com pausa automática habilitada

  Um banco de dados pausado automaticamente retoma na primeira tentativa de conexão, e essa tentativa pode falhar com o erro 40613 enquanto o banco de dados recomeça. Defina connection_timeout em pelo menos 60 e tente estabelecer a primeira conexão novamente. Para mais informações, consulte Banco de Dados SQL do Azure serverless e Pausa automática e retomada automática.

• Servidor sobrecarregado

  Aumentar connection_retries e 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 migração

Esses erros ocorrem durante as operações de migração do Django em relação a SQL Server.

Problemas de SQL bruto e GROUP BY

Esses erros ocorrem quando consultas brutas ou anotadas com uma cláusula GROUP BY passam pela etapa de reescrita de marcadores de posição no backend.

IndexError em GROUP BY com %% com caractere de escape e parâmetros reais

Sintomas:

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

A consulta funciona sem a cláusula GROUP BY e funciona sem o literal com caractere de escape %%, mas falha quando ambos estão presentes junto com um parâmetro real %s.

Solução: Atualize para uma versão atual mssql-django . O backend restringe o regex de reescrita de marcadores somente a %% e %s, então os literais %% escapados são preservados exatamente como estão e nenhum marcador fantasma é injetado.

NotImplementedError para IntegerChoices em consultas brutas GROUP BY

Sintomas:

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

O mesmo valor de enum funciona em consultas ORM e em consultas brutas sem GROUP BY, mas falha quando passado como parâmetro para uma consulta bruta que contém uma GROUP BY cláusula.

Solução: Atualize para uma versão atual mssql-django . O backend usa isinstance para verificações do tipo de parâmetro no caminho GROUP BY, então IntegerChoices (uma subclasse de int) é vinculado corretamente. bool ainda se vincula a bit, e o simples int permanece inalterado.

Problemas com a consulta Regex

__regex ou __iregex retorna sem linhas

Sintomas: A consulta roda sem erro e retorna um conjunto de resultados vazio, mesmo que as linhas correspondam ao padrão.

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

Porque: dbo.REGEXP_LIKE ignora literalmente o espaço em branco no padrão. O padrão é tratado como correspondente a ^Widget\d+$, algo que nenhum valor que contenha um espaço pode satisfazer. Nada surge, então o resultado vazio parece um problema de dados.

Solução: Escrever espaços em branco como escape ou classe de caractere:

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

Cannot find ... dbo.REGEXP_LIKE

Sintomas:

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)')

No caminho 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: O assembly CLR não está instalado no banco de dados que você está consultando. Ele é instalado por banco de dados, não por servidor.

Solução: Execute python manage.py install_regex_clr <database> nesse banco de dados. Execute-o novamente depois de excluir e recriar um banco de dados. Veja Configurar buscas com regex.

Problemas de data e hora

Now() os valores são deslocados quando USE_TZ=True

Sintomas:

Os carimbos de data e hora gravados com Now(), auto_now ou auto_now_add do Django são deslocados quando o fuso horário do host do SQL Server não está em UTC.

Solução: Atualize para uma versão atual mssql-django . O backend gera SQL com reconhecimento de fuso horário Now(), preserva deslocamentos de datetimeoffset e lê dados de fuso horário por meio de zoneinfo e tzdata.

AttributeError ao chamar .explain()

Sintomas:

AttributeError: ... explain_format ...

Solução: Atualize para uma versão atual mssql-django . Os handles backend explicam os metadados de todas as versões suportadas do Django.

Não é possível alterar o AutoField

Sintomas:

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

Solução: SQL Server não dá suporte à alteração de um campo de ou para AutoField. Crie um novo modelo com o tipo de campo desejado, migre os dados manualmente e solte a tabela antiga. Para obter soluções alternativas, consulte migrações de banco de dados com mssql-django.

Falha ao renomear com restrição de chave estrangeira

Sintomas:

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

Solução: SQL Server requer a remoção de restrições de chave estrangeira antes de renomear colunas. Use SeparateDatabaseAndState em sua migração. Para obter um exemplo, consulte migrações de banco de dados com mssql-django.

Problemas de codificação

Erros de codificação normalmente ocorrem no caminho pyodbc quando pyodbc dados de caracteres do SQL Server são interpretados incorretamente.

Erros de codificação Unicode

Sintomas:

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

Solução: Configurar a codificação pyodbc no dicionário OPTIONS. O caminho mssql-python ignora unicode_results.

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

Problemas de FreeTDS

O FreeTDS requer uma configuração específica para pyodbc que difere do driver ODBC da Microsoft.

Erro host_is_server

Sintomas:

A conexão falha ao usar o FreeTDS sem especificar host_is_server.

Solução: defina host_is_server para True quando você usar o FreeTDS:

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

Para obter mais informações sobre a configuração do FreeTDS, consulte as opções de conexão para mssql-django.

Testar problemas de banco de dados

A criação e a destruição do banco de dados de teste podem falhar dependendo do método de autenticação.

Não é possível criar um banco de dados de teste com identidade gerenciada

Sintomas:

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

Ou:

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

O executor de testes falha quando em criar ou destruir o banco de dados de teste quando você usa a autenticação ActiveDirectoryMsi (identidade gerenciada). Essa limitação existe porque:

• As credenciais de identidade gerenciada são obtidas do ambiente do host (como Azure VM e Serviço de Aplicativo).

• O executor de testes tenta se conectar usando as credenciais do banco de dados test durante a desmontagem.

• A identidade gerenciada pode receber funções no nível do banco de dados, mas a criação e a exclusão do banco de dados de teste geralmente exigem permissões no nível do servidor que os executores de teste geralmente não têm.

Métodos de autenticação afetados:

• ActiveDirectoryMsi (identidade gerenciada do Azure)
• ActiveDirectoryServicePrincipal (quando configurado somente no escopo do servidor)

Métodos de autenticação com suporte (a criação do banco de dados de teste funciona):

• ActiveDirectoryPassword
• ActiveDirectoryIntegrated
• Autenticação sql (nome de usuário/senha)

Compromissos de autenticação para ambientes de teste

Soluções:

• Para desenvolvimento: use o sinalizador --keepdb para ignorar a desinstalação do banco de dados de teste:

  python manage.py test --keepdb
  

• Para pipelines de CI/CD: crie previamente um banco de dados de teste dedicado e conceda permissões CREATE TABLE e ALTER à identidade gerenciada:

  -- 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 a autenticação do SQL para ambientes de teste ou mude para ActiveDirectoryPassword nos executores de teste de CI/CD.

Procedimentos de reversão

Quando uma migração falhar no meio do caminho, use esta sequência de reversão para retornar a um bom estado conhecido:

1. Pare as gravações de aplicativo para evitar descompasso de esquema adicional.

2. Inspecione o estado de migração:

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

3. Reverta para a última migração boa conhecida:

   python manage.py migrate <app_label> <previous_migration>
   

4. Se o esquema e o histórico de migração divergirem, repare o estado com cuidado usando --fake somente depois de verificar o esquema real do banco de dados.

5. Execute novamente as migrações em um ambiente de preparo primeiro e tente novamente a produção.

Problemas de docker e contêiner

Imagens de contêiner exigem instalação explícita de drivers ODBC e dependências de build quando você usa o caminho padrão do pyodbc. A opção mssql-python não tem uma instalação separada do driver ODBC, mas ainda precisa do ambiente de execução do unixODBC, porque o backend importa o pyodbc quando o Django o carrega.

Driver ODBC não encontrado no contêiner

Sintomas:

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

Possíveis causas e soluções:

• Driver ODBC não instalado na imagem do contêiner

  As imagens base Slim ou Alpine não incluem o driver ODBC. Adicione o repositório Microsoft APT e instale msodbcsql18 no seu Dockerfile quando usar o pyodbc. Consulte Implantar no Serviço de Aplicativo para obter um exemplo completo do Dockerfile.

• Pacote ausente unixodbc-dev

  O pacote wheel pyodbc é vinculado a libodbc.so. Instale unixodbc-dev (Debian/Ubuntu) ou unixODBC-devel (RHEL/Fedora) antes de instalar Python pacotes.

• apt-get autoremove removido libgssapi-krb5-2 após a instalação do driver

  msodbcsql18 carrega libgssapi-krb5-2 em tempo de execução sem declará-lo como dependência. A biblioteca geralmente chega como uma dependência de curl, então purgar curl com --auto-remove, ou executar apt-get autoremove depois, remove essa dependência. A imagem é gerada sem erros e depois todas as conexões falham. Instale libgssapi-krb5-2 explicitamente e não faça a remoção automática após a instalação do driver.

O driver 17 foi reportado como ausente quando você instalou a versão 18

Sintomas:

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

A mensagem de erro menciona a versão 17, mas odbcinst -q -d mostra a versão 18 registrada e dpkg -l msodbcsql18 mostra que ela está instalada.

Causa: A versão 18 está registrada, mas não carrega, então o mssql-django volta para a versão 17, que não está instalada. O mecanismo de fallback informa qual driver ele tentou em segundo lugar, não o que falhou.

Solução: instalar libgssapi-krb5-2 e reconstruir. Veja a nota de autoremove acima para saber como a biblioteca desaparece.

Erro ao carregar o módulo pyodbc em um contêiner

Sintomas:

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

Causa: A imagem não tem runtime de unixODBC. O mssql-django importa o pyodbc quando o Django carrega o backend, então esse erro também acontece no caminho mssql-python, antes que qualquer conexão seja tentada.

Solução: Instalar unixodbc (ou unixodbc-dev).

Driver MSSQL-Python falha ao carregar

Sintomas:

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

Causa: O driver fornecido com mssql-python precisa das bibliotecas de tempo de execução do Kerberos, que as imagens base slim não incluem.

Solução: Instalar libkrb5-3 e libgssapi-krb5-2.

pyodbc falha em criar em imagens finas

Sintomas:

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

Ou:

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

Solução: Instale as dependências de compilação antes de pip install:

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

Como alternativa, use um build de vários estágios para manter a imagem final pequena:

# 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/*

O contêiner não pode se conectar ao SQL Server

Sintomas:

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

Possíveis causas e soluções:

• Nome do serviço do Docker Compose não é usado como host

  Ao usar o Docker Compose, defina DB_HOST como o nome do serviço (por exemplo, db), não localhost ou 127.0.0.1.

• SQL Server contêiner não está pronto

  O contêiner SQL Server leva vários segundos para ser iniciado. Adicionar uma verificação de saúde ou um atraso na inicialização:

  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
  

• Conflitos de mapeamento de porta

  Se outra instância do SQL Server estiver em execução no host, altere a porta exposta (por exemplo1434:1433) e atualize a configuração do Django adequadamente.

Recuperação de erros transitórios do SQL do Azure

O mssql-django back-end detecta automaticamente as conexões com o Banco de Dados SQL do Azure e a Instância Gerenciada de SQL do Azure consultando SERVERPROPERTY('EngineEdition'). Ao executar em SQL do Azure, o back-end tenta novamente conexões em erros transitórios (como limites de recursos temporários ou breves interrupções de rede).

Você pode ajustar esse comportamento com as opções connection_retries e connection_retry_backoff_time:

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

Essas configurações se aplicam somente ao estabelecimento de conexão inicial. O back-end não tenta novamente consultas com falha. Se uma consulta falhar com um erro transitório após a conexão ser estabelecida, a exceção será propagada para o código do aplicativo. Use a lógica de repetição no nível do aplicativo (por exemplo, django-retry-db ou um middleware personalizado) para resiliência no nível de consulta.

Consultas lentas e regressões de plano

Esses problemas geralmente precisam de análise do lado do servidor junto com a revisão de consulta no nível do Django.

A consulta fica lenta ou começa a expirar por tempo limite

Sintomas:

O mesmo conjunto de consultas fica mais lento ao longo do tempo ou passa a expirar por tempo limite após uma implantação, uma alteração de índice ou uma atualização de estatísticas.

Possíveis causas e soluções:

• Começar com relatórios de desempenho internos

  Para SQL Server e Instância Gerenciada de SQL do Azure, abra o Painel de Desempenho no SQL Server Management Studio. No Banco de Dados SQL do Azure, abra Análise de desempenho de consultas para Banco de Dados SQL do Azure. Essas ferramentas geralmente são uma etapa inicial melhor do que consultas ad hoc nas DMVs, porque identificam rapidamente consultas de alto custo, esperas e pressão de recursos.

• Regressão de plano

  Use Repositório de Consultas para identificar a consulta lenta e verificar se há vários planos para ela. Comece pelas exibições Regressed Queries e Top Resource Consuming Queries descritas em Práticas recomendadas para monitorar cargas de trabalho com o Repositório de Consultas.

• Plano de execução ineficiente

  Abra um plano de execução real para a instrução e verifique se há verificações de tabela ou índice,pesquisas extensas de chave, despejos de hash ou estimativas de linhas imprecisas. Para obter informações em segundo plano, consulte a visão geral do plano de execução.

• Gargalo incorreto identificado

  Se a consulta não estiver limitada pela CPU, use as estatísticas de espera do Repositório de Consultas e Identificar gargalos para distinguir entre CPU, memória, E/S de disco, bloqueio e pressão nas conexões.

• Correção aplicada na camada errada

  Aplique a menor correção eficaz: adicione ou ajuste índices, atualize estatísticas, reduza as colunas e as linhas selecionadas ou divida gravações grandes em lotes. Se você precisar de uma mitigação de emergência, poderá usar um DBA para forçar temporariamente um plano bom conhecido no Repositório de Consultas enquanto você corrige a causa raiz.

Usar o dbshell para consultas interativas

O comando de gerenciamento do dbshell Django abre um shell SQL interativo conectado ao banco de dados:

python manage.py dbshell

O back-end usa sqlcmd quando você configura o driver ODBC Microsoft ou isql quando usa o FreeTDS. Verifique se a ferramenta está em seu PATH:

• Windows: sqlcmd está incluído nas ferramentas do SQL Server, ou você pode baixá-lo separadamente.
• Linux e macOS: instale mssql-tools18 no repositório Microsoft.

Conteúdo relacionado

• Referência de configuração mssql-django
• Opções de conexão para mssql-django
• Lógica de repetição e resiliência da conexão com mssql-django
• Limitações e recursos sem suporte no mssql-django
• Painel de Desempenho
• Análise de desempenho de consulta para o Banco de Dados SQL do Azure
• Monitorar o desempenho usando o Repositório de Consultas
• Analisar um plano de execução real
• Solução de problemas wiki
• perguntas frequentes