Resolução de problemas de mssql-django

Diagnostice e resolva problemas comuns no mssql-django backend do SQL Server, Base de Dados SQL do Azure, Azure SQL Managed Instance e base de dados SQL no Microsoft Fabric.

mssql-django A versão 2.0 suporta o caminho de driver padrão pyodbc e um caminho de driver mssql-python com opção de opt-in. Para mais informações, consulte Selecionar o driver da base de dados para mssql-django.

Problemas de conexão

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

O driver ODBC não encontrado no caminho pyodbc

Sintomas:

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

Or:

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

  Instala o driver Microsoft ODBC para SQL Server quando usares o caminho pyodbc predefinido. Para links de download, consulte Download ODBC Driver for SQL Server. O caminho mssql-python não usa um driver ODBC instalado externamente.

• Múltiplas versões de drivers instaladas

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

• Verifique os drivers instalados

  • Em Linux/macOS, execute odbcinst -q -d.
  • No sistema Windows, consulte Fontes de Dados ODBC em Ferramentas Administrativas.

O mssql-python rejeita uma opção de ligação

Sintomas:

Um alias que define "python_driver": "mssql_python" falha durante a configuração da ligação depois de mover palavras-chave pyodbc connection-string 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 está em minúsculas, pelo que uma palavra-chave que escreveste como LongAsMax aparece como longasmax. ConnectionStringParseError não faz parte da hierarquia DB-API exceções, por isso o Django não a reencapsula como um django.db.utils erro.

Possíveis causas e soluções:

• palavra-chave exclusiva do pyodbc em extra_params

  O caminho mssql-python valida extra_params em relação a uma lista de permissões. DRIVER e APP são reservados para o condutor e produzem o Reserved keyword formulário. DSN, SERVERNAME, MARS_Connection e palavras-chave exclusivas de 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 a forma Unknown keyword. Remova a palavra-chave ou utilize o caminho predefinido do pyodbc para um alias que necessite dessa opção ODBC.

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

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

A dependência MSSQL-Python é demasiado antiga

Sintomas:

Um alias que define "python_driver": "mssql_python" falha na configuração da ligação com um destes 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"'.

A segunda forma significa que o mssql_python módulo não é importável de todo.

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

O recurso do driver 17 não se aplica ao mssql-python

Sintomas:

Um alias que se configura "python_driver": "mssql_python" continua a falhar mesmo estando instalado o Microsoft ODBC Driver 17 para SQL Server.

Não há erro distintivo neste caso. A via mssql-python ignora silenciosamente a opção driver, pelo que a ligação falha com o erro subjacente aplicável. Se moveres o nome do controlador para extra_params em vez disso, obténs o erro Reserved keyword 'driver'. Consulte o mssql-python rejeita uma opção de ligação.

Solução: Use o caminho predefinido do pyodbc se o alias tiver de usar um Driver ODBC 17 instalado externamente. O caminho mssql-python não recorre ao Driver 17 e ignora a opção driver. Esse caminho não precisa de um driver ODBC instalado separadamente.

Ligação recusada

Sintomas:

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

Possíveis causas e soluções:

• TCP/IP não ativado no SQL Server

  • Abra o Gestor de Configuração do SQL Server.
  • Em SQL Server Network Configuration, ative TCP/IP.
  • Em TCP/Propriedades IP, ative o endereço IP utilizado para a ligação.
  • Reinicie o serviço SQL Server.

• Firewall a bloquear a porta 1433

  • Verifica se as regras do firewall permitem ligações de entrada na porta 1433.
  • Para SQL do Azure, adicione o IP do seu cliente nas definições do firewall do portal Azure.

• Nome de servidor ou porta errados

  Verifica os valores HOST e PORT na configuração.

Início de sessão falhado

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

  Verifica o nome de utilizador e a palavra-passe.

• A base de dados em NAME não existe

  No SQL Server, o caminho mssql-python apresenta a mesma OperationalError mensagem com a mesma mensagem que uma palavra-passe errada, por isso a mensagem sozinha não te diz qual delas atingiste. Confirma que a base de dados existe antes de mudares as credenciais. Aponte NAME para master para testar o início de sessão isoladamente: se a ligação for bem-sucedida, as credenciais estão corretas e o problema está na base de dados. O caminho pyodbc reporta este caso separadamente como Cannot open database "<database>" requested by the login. The login failed. (4060).

  Base de Dados SQL do Azure reporta este caso de forma diferente. A via 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 indica o nome do servidor, mas o nome do servidor está correto. Verifique NAME em vez disso.

• Utilizador não existe

  Confirme que o login está mapeado para um utilizador na base de dados de destino.

• Autenticação do SQL Server desativada

  Ative a autenticação em modo misto ou utilize a autenticação Windows ou Microsoft Entra.

Tempo limite de ligação

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

  Aumente connection_timeout em OPTIONS.

• Base de Dados SQL do Azure serverless com pausa automática ativada

  Uma base de dados em pausa automática recomeça na primeira tentativa de ligação, e essa tentativa pode falhar com o erro 40613 enquanto a base de dados recomeça. Define connection_timeout para pelo menos 60 e tenta novamente a primeira ligação. Para mais informações, consulte Base de Dados SQL do Azure serverless e Pausa automática e reativação automática.

• Servidor sobrecarregado

  Aumente 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,
  },
  

Questões relacionadas com a migração

Estes erros ocorrem durante as operações de migração do Django contra o SQL Server.

Problemas de SQL bruto e GROUP BY

Estes erros ocorrem quando consultas em bruto ou anotadas com uma cláusula GROUP BY passam pela etapa de reescrita de marcadores de posição do backend.

IndexError em GRUPO BY com parâmetros escapados %% e reais

Sintomas:

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

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

Solução: Atualize para uma versão mais recente mssql-django. O backend restringe a regex de reescrita de marcadores de posição apenas a %% e %s, pelo que os literais %% escapados são preservados na íntegra e não são injetados marcadores de posição fantasma.

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 mssql-django versão mais recente. O backend utiliza isinstance para verificar os tipos dos parâmetros no caminho GROUP BY, pelo que IntegerChoices (uma subclasse de int) é corretamente associada. bool continua a associar bit, e o simples int mantém-se inalterado.

Problemas de consulta Regex

__regex ou __iregex não devolve quaisquer linhas

Sintomas: A consulta corre sem erro e devolve 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

Causa: dbo.REGEXP_LIKE ignora o espaço em branco literal no padrão. A correspondência do padrão é feita como se este fosse ^Widget\d+$, o que nenhum valor que contenha um espaço pode satisfazer. Nada surge, por isso o resultado vazio parece um problema de dados.

Solução: Escrever espaços em branco como escape ou classe 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

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 na base de dados que estás a consultar. É instalado por base de dados, não por servidor.

Solução: Executar python manage.py install_regex_clr <database> nessa base de dados. Execute-o novamente depois de eliminar e recriar uma base de dados. Veja Configurar consultas de regex.

Questões de data e hora

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

Sintomas:

Carimbos temporais escritos com DjangoNow(), auto_now, ou auto_now_add são deslocados quando o fuso horário do host do SQL Server não é UTC.

Solução: Atualize para uma versão mais recente mssql-django. O backend gera SQL com reconhecimento de fuso horário Now(), preserva os desvios de datetimeoffset e lê dados de fuso horário através de zoneinfo e tzdata.

AttributeError ao chamar .explain()

Sintomas:

AttributeError: ... explain_format ...

Solução: Atualize para uma versão mais recente mssql-django. Os handles do 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: O SQL Server não suporta alterar um campo de ou para AutoField. Crie um novo modelo com o tipo de campo desejado, migre os dados manualmente e depois retire a tabela antiga. Para soluções alternativas, veja Migrações de bases de dados com mssql-django.

Não é possível mudar o nome devido a uma restrição de chave estrangeira

Sintomas:

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

Solução: O SQL Server exige eliminar restrições de chave estrangeira antes de renomear as colunas. Use SeparateDatabaseAndState na sua migração. Para um exemplo, veja Migrações de bases de dados com mssql-django.

Problemas de codificação

Os erros de codificação ocorrem tipicamente na via do pyodbc quando pyodbc interpreta mal os dados de carateres do SQL Server.

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 do FreeTDS

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

host_is_server erro

Sintomas:

A ligação falha ao usar FreeTDS sem especificar host_is_server.

Solução: Defina host_is_server como True quando utilizar o FreeTDS:

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

Para mais informações sobre a configuração do FreeTDS, consulte Opções de ligação para mssql-django.

Problemas com bases de dados de testes

A criação e destruição de bases de dados de teste pode falhar dependendo do seu método de autenticação.

Não é possível criar uma base de dados de teste com identidade gerida

Sintomas:

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

Or:

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

O executor de testes não consegue criar nem destruir a base de dados de teste quando usa a autenticação ActiveDirectoryMsi (identidade gerida). Esta limitação existe porque:

• As credenciais de identidade gerida são obtidas a partir do ambiente anfitrião (como Azure VM e App Service).

• O executor de testes tenta estabelecer ligação usando as credenciais da base de dados de teste durante a fase de desmontagem.

• A identidade gerida pode receber funções ao nível da base de dados, mas a criação e eliminação de bases de dados de teste normalmente requerem permissões a nível de servidor que os executores de testes muitas vezes não têm.

Métodos de autenticação afetados:

• ActiveDirectoryMsi(Identidade gerida do Azure)
• ActiveDirectoryServicePrincipal (quando configurado apenas no âmbito do servidor)

Métodos de autenticação suportados (testes de criação de bases de dados):

• ActiveDirectoryPassword
• ActiveDirectoryIntegrated
• Autenticação SQL (nome de utilizador/palavra-passe)

Compensações na autenticação para ambientes de teste

Soluções:

• Para desenvolvimento: Use a opção --keepdb para ignorar a eliminação da base de dados de teste:

  python manage.py test --keepdb
  

• Para pipelines de CI/CD: Criar previamente uma base de dados de teste dedicada e conceder à identidade gerida as permissões CREATE TABLE e ALTER:

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

Procedimentos de reversão

Quando uma migração falhar a meio do processo, utilize esta sequência de reversão para regressar a um estado válido conhecido:

1. Interrompa as operações de escrita da aplicação para evitar mais divergências no esquema.

2. Inspecionar o estado da migração:

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

3. Reverter para a última migração válida conhecida:

   python manage.py migrate <app_label> <previous_migration>
   

4. Se o esquema e o histórico de migração divergirem, repare cuidadosamente o estado com --fake só depois de verificar o esquema real da base de dados.

5. Reexecute as migrações num ambiente de staging primeiro, depois tente novamente a produção.

Problemas com dockers e contentores

As imagens do contentor requerem dependências explícitas de instalação e construção de drivers ODBC quando se usa o caminho pyodbc predefinido. O caminho mssql-python não tem instalação separada de drivers ODBC, mas ainda precisa do runtime unixODBC, porque o backend importa pyodbc quando o Django o carrega.

Controlador ODBC não encontrado no contentor

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 contentor

  As imagens base Slim ou Alpine não incluem o controlador ODBC. Adiciona o repositório Microsoft APT e instala msodbcsql18 no teu Dockerfile quando usares o pyodbc. Consulte Deploy to App Service para um exemplo completo do Dockerfile.

• Pacote em falta unixodbc-dev

  A pyodbc roda liga-se contra libodbc.so. Instale unixodbc-dev (Debian/Ubuntu) ou unixODBC-devel (RHEL/Fedora) antes de instalar pacotes em Python.

• 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 o declarar como dependência. A biblioteca normalmente surge como uma dependência de curl, por isso purgar curl com --auto-remove, ou executar apt-get autoremove depois, remove-a. A imagem é criada sem erros, mas depois todas as conexões falham. Instala libgssapi-krb5-2 explicitamente e não executes a remoção automática após a instalação do controlador.

O driver 17 foi reportado em falta quando instalaste 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)")

O erro indica a versão 17, mas odbcinst -q -d mostra a versão 18 registada e dpkg -l msodbcsql18 mostra que está instalada.

Causa: A versão 18 está registada mas não carrega, por isso o mssql-django volta à versão 17, que não está instalada. O mecanismo de recurso indica o controlador que tentou usar em segundo lugar, não o que falhou.

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

Erro de carregamento do módulo pyodbc num contentor

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 possui o ambiente de execução unixODBC. O mssql-django importa o pyodbc quando o Django carrega o backend, por isso este erro também acontece no caminho mssql-python, antes de qualquer ligação ser 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 controlador fornecido com mssql-python precisa das bibliotecas de execução do Kerberos, que as imagens de base slim não incluem.

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

O pyodbc não consegue desenvolver imagens finas

Sintomas:

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

Or:

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

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

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

Alternativamente, use uma construção em múltiplas fases 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 contentor não consegue ligar-se 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 para o nome do serviço (por exemplo, db), not localhost ou 127.0.0.1.

• Contentor SQL Server não pronto

  O contentor do SQL Server demora vários segundos a arrancar. Adicione um exame de saúde ou atraso no arranque:

  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 portas

  Se outra instância de SQL Server estiver a correr no host, altera a porta exposta (por exemplo, 1434:1433) e atualiza a configuração do Django em conformidade.

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

O mssql-django back-end deteta automaticamente as ligações ao Base de Dados SQL do Azure e ao Azure SQL Managed Instance consultando SERVERPROPERTY('EngineEdition'). Ao correr contra SQL do Azure, o backend tenta novamente ligações em erro transitório (como limites temporários de recursos ou breves interrupções de rede).

Pode ajustar este comportamento com as connection_retries e connection_retry_backoff_time OPÇÕES:

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

Estas definições aplicam-se apenas ao estabelecimento inicial da ligação. O backend não tenta novamente as consultas que falharam. Se uma consulta falhar com um erro transitório após a ligação estar estabelecida, a exceção propaga-se para o código da sua aplicação. Utilize lógica de repetição ao nível da aplicação (por exemplo, django-retry-db ou middleware personalizado) para resiliência ao nível das consultas.

Consultas lentas e regressões de planos

Estes problemas normalmente requerem análise do lado do servidor juntamente com revisão de consultas ao nível do Django.

A consulta fica mais lenta ou começa a expirar

Sintomas:

O mesmo conjunto de consultas torna-se mais lento com o tempo, ou começa a expirar após uma implementação, alteração de índice ou atualização de estatísticas.

Possíveis causas e soluções:

• Comece com relatórios de desempenho incorporados

  Para SQL Server e Azure SQL Managed Instance, abra o Performance Dashboard no SQL Server Management Studio. Para Base de Dados SQL do Azure, abra Query Performance Insight for Base de Dados SQL do Azure. Estas ferramentas são geralmente um melhor primeiro passo do que as consultas ad hoc no DMV, pois rapidamente revelam consultas dispendiosas, esperas e pressão de recursos.

• Regressão do plano

  Utilize a Query Store para encontrar a consulta lenta e verificar se tem múltiplos planos. Comece pelas vistas de Consultas Regressadas e Consultas que Consomem Mais Recursos descritas nas Melhores Práticas para monitorizar cargas de trabalho com a Query Store.

• Plano de execução ineficiente

  Abra um plano de execução real da instrução e verifique se há varrimentos de tabelas ou de índices, pesquisas de chave dispendiosas, derramamentos de hash ou estimativas de linhas imprecisas. Para contextualizar, veja Visão geral do plano de execução.

• Gargalo errado identificado

  Se a consulta não estiver dependente da CPU, utilize as estatísticas de espera do Query Store e Identificar estrangulamentos para distinguir entre problemas de CPU, memória, E/S do disco, bloqueios e sobrecarga de ligações.

• Correção aplicada na camada errada

  Aplique a correção eficaz mínima: adicione ou ajuste índices, atualize estatísticas, reduza o número de colunas e linhas selecionadas ou agrupe operações de escrita de grande volume em lotes. Se precisar de uma mitigação de emergência, um DBA pode forçar temporariamente um plano, já conhecido por ser bom, no Query Store enquanto corrige a causa raiz.

Utilize dbshell para consultas interativas

O comando de gestão do dbshell Django abre um shell SQL interativo ligado à sua base de dados:

python manage.py dbshell

O backend utiliza sqlcmd quando configura o controlador ODBC da Microsoft, ou isql quando utiliza o FreeTDS. Verifica se a ferramenta está no teu PATH:

• Windows: sqlcmd está incluído com as ferramentas do SQL Server, ou pode descarregá-lo separadamente.
• Linux e macOS: Instalar mssql-tools18 a partir do repositório da Microsoft.

Conteúdo relacionado

• Referência de configuração MSSQL-Django
• Opções de ligação para mssql-django
• Lógica de repetição e resiliência da conexão com mssql-django
• Limitações e funcionalidades não suportadas no mssql-django
• Painel de Desempenho
• Query Performance Insight para a Base de Dados SQL do Azure
• Monitorize o desempenho usando o Query Store
• Analise um plano de execução real
• Wiki de resolução de problemas
• Perguntas Frequentes