Risolvere i problemi relativi a mssql-django

Diagnosticare e risolvere i problemi comuni relativi al mssql-django back-end per SQL Server, database SQL di Azure, Istanza gestita di SQL di Azure e database SQL in Microsoft Fabric.

mssql-django La versione 2.0 supporta il percorso del driver predefinito pyodbc e un percorso del driver mssql-python opzionale. Per ulteriori informazioni, vedi Seleziona il driver del database per mssql-django.

Problemi di connessione

Questa sezione illustra gli errori di connessione più comuni e come risolverli.

Il driver ODBC non è stato trovato sul percorso pyodbc

Sintomi:

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

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

Possibili cause e soluzioni:

Driver ODBC non installato

Installa il driver Microsoft ODBC per SQL Server quando usi il percorso pyodbc predefinito. Per i collegamenti per il download, vedere Scaricare il driver ODBC per SQL Server. Il percorso mssql-python non utilizza un driver ODBC installato esternamente.

Più versioni dei driver installate

Specificare il nome o il percorso esatto del driver in 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",
        },
    },
}

In Linux specificare il percorso completo:

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

Controlla i driver installati
- In Linux/macOS eseguire odbcinst -q -d.
- In Windows selezionare Origini dati ODBC in Strumenti di amministrazione.

MSSQL-Python rifiuta un'opzione di connessione

Sintomi:

Un alias che si imposta "python_driver": "mssql_python" fallisce durante l'impostazione della connessione dopo che si spostano le parole chiave pyodbc connection-string in OPTIONS["extra_params"], con uno di questi errori:

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

Il nome della parola chiave nel messaggio è minuscolo, quindi una parola chiave che hai scritto come LongAsMax appare come longasmax. ConnectionStringParseError non fa parte della gerarchia delle eccezioni DB-API, quindi Django non lo riavvolge come django.db.utils errore.

Possibili cause e soluzioni:

Parola chiave solo per pyodbc in extra_params

Il percorso mssql-python convalida extra_params rispetto a un elenco di elementi consentiti. DRIVER e APP sono riservati al conducente e producono il Reserved keyword modulo. DSN, SERVERNAME, MARS_Connection e parole chiave supportate solo da pyodbc come LongAsMax, ColumnEncryption, WSID, AnsiNPW, UseFMTONLY, Regional, QuotedId, Current Language, Network Library, Description e Connect Timeout non sono nell'elenco degli elementi consentiti e producono il formato Unknown keyword. Rimuovi la parola chiave, oppure usa il percorso pyodbc predefinito per un alias che richiede quell'opzione ODBC.
Opzione driver prevista per controllare mssql-python

Il percorso mssql-python ignora driver, dsn, host_is_server, e unicode_results. HOST e PORT diventano SERVER=<server>,<port>, e un vuoto HOST diventa localhost.

La dipendenza da MSSQL-Python è troppo vecchia

Sintomi:

Un alias che imposta "python_driver": "mssql_python" fallisce all'instaurazione della connessione con uno di questi errori:

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

Il secondo modulo significa che il mssql_python modulo non è affatto importabile.

Soluzione: installare mssql-python>=1.15.0. mssql-django La 2.0 dichiara mssql-python>=1.15.0, quindi una normale pip install mssql-django risolve una versione compatibile sulle piattaforme supportate.

Il fallback del driver 17 non si applica a mssql-python

Sintomi:

Un alias che si imposta "python_driver": "mssql_python" continua a fallire anche se è installato il driver Microsoft ODBC 17 per SQL Server.

Non c'è alcun errore distintivo per questo caso. Il percorso mssql-python ignora silenziosamente l'opzione driver , quindi la connessione fallisce con l'errore sottostante applicato. Se sposti invece il nome del driver in extra_params, ottieni un errore Reserved keyword 'driver'. Vedi mssql-python rifiuta un'opzione di connessione.

Soluzione: Usa il percorso pyodbc predefinito se l'alias deve utilizzare un driver ODBC 17 installato esternamente. Il percorso mssql-python non torna al Driver 17 e ignora l'opzione driver . Quel percorso non richiede un driver ODBC installato separatamente.

Connessione rifiutata

Sintomi:

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

Possibili cause e soluzioni:

TCP/IP non abilitato in SQL Server
- Aprire Gestione configurazione SQL Server.
- In SQL Server Configurazione di rete abilitare TCP/IP.
- In Proprietà TCP/IP attivare l'indirizzo IP usato per la connessione.
- Riavviare il servizio SQL Server.
Firewall che blocca la porta 1433
- Verificare che le regole del firewall consentano le connessioni in ingresso sulla porta 1433.
- Per Azure SQL, aggiungi l'indirizzo IP del client nelle impostazioni del firewall nel portale di Azure.
Nome o porta del server non corretto

Verificare i valori di HOST e PORT nella configurazione.

Sintomi:

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

Sul percorso mssql-python:

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

Possibili cause e soluzioni:

Credenziali non corrette

Verificare il nome utente e la password.
Il database in NAME non esiste

In SQL Server, il percorso mssql-python genera lo stesso OperationalError con lo stesso messaggio di una password errata, quindi il solo messaggio non ti dice quale dei due casi si è verificato. Conferma che il database esista prima di cambiare le credenziali. Punta NAME su master per testare l’accesso in modo indipendente: se la connessione riesce, le credenziali sono corrette e il problema è il database. Il percorso pyodbc riporta questo caso separatamente come Cannot open database "<database>" requested by the login. The login failed. (4060).

database SQL di Azure riporta questo caso in modo diverso. Il percorso mssql-python genera Driver Error: General error; DDBC Error: [Microsoft][SQL Server]Cannot open server "<server>" requested by the login. The login failed. Il messaggio indica il server, ma il nome del server è corretto. Controlla NAME invece.
L'utente non esiste

Verificare che l'account di accesso sia mappato a un utente nel database di destinazione.
Autenticazione di SQL Server disabilitata

Abilitare l'autenticazione in modalità mista oppure usare l'autenticazione di Windows o di Microsoft Entra.

Timeout della connessione

Sintomi:

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

Possibili cause e soluzioni:

Latenza di rete

Aumento connection_timeout delle opzioni.
database SQL di Azure serverless con auto-pausa abilitata

Un database in pausa automatica riprende al primo tentativo di connessione, e questo tentativo può fallire con l'errore 40613 mentre il database riprende. Imposta connection_timeout almeno a 60 e riprova la prima connessione. Per maggiori informazioni, consulta database SQL di Azure serverless e Pausa automatica e ripresa automatica.

Server sovraccarico

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

Problemi di migrazione

Questi errori si verificano durante le operazioni di migrazione di Django su SQL Server.

Problemi di SQL grezzo e GROUP BY

Questi errori si verificano quando query grezze o annotate contenenti una clausola GROUP BY passano per la fase di riscrittura dei segnaposto del backend.

`IndexError` su GROUP BY con parametri con caratteri di escape `%%` e parametri reali

Sintomi:

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

La query funziona senza la GROUP BY clausola e senza il letterale sfuggito %% , ma fallisce quando entrambi sono presenti insieme a un parametro reale %s .

Soluzione: Aggiorna a una versione attuale mssql-django . Il backend restringe la regex di riscrittura dei segnaposto ai soli %% e %s, così i letterali con escape %% sono preservati alla lettera e non vengono inseriti segnaposto fantasma.

`NotImplementedError` per `IntegerChoices` nelle query GROUP BY non elaborate

Sintomi:

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

Lo stesso valore enum funziona sia nelle query ORM sia nelle raw query senza GROUP BY, ma non funziona quando viene passato come parametro a una raw query che contiene una clausola GROUP BY.

Soluzione: Aggiorna a una versione attuale mssql-django . Il backend usa isinstance per i controlli dei tipi di parametro nel percorso GROUP BY, quindi IntegerChoices (una sottoclasse di int) viene associato correttamente. bool associa ancora il bit, e il solo int resta invariato.

Problemi di ricerca Regex

`regex` oppure `iregex` non restituisce righe

Sintomi: La query viene eseguita senza errore e restituisce un set di risultati vuoto, anche se le righe corrispondono al pattern.

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

Causa: dbo.REGEXP_LIKE ignora letteralmente lo spazio bianco nel motivo. Il pattern è abbinato come se fosse ^Widget\d+$, che nessun valore contenente uno spazio può soddisfare. Non viene generato nulla, quindi il risultato vuoto sembra un problema di dati.

Soluzione: Scrivi spazi in bianco come escape o classe di carattere:

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

`Cannot find ... dbo.REGEXP_LIKE`

Sintomi:

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

Sul percorso 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: l'assembly CLR non è installato nel database che stai interrogando. Viene installato per database, non per server.

Soluzione: Esegui python manage.py install_regex_clr <database> contro quel database. Rieseguilo dopo aver eliminato e ricreato un database. Vedi Configura ricerche regex.

Problemi relativi a data e ora

`Now()` i valori vengono spostati quando `USE_TZ=True`

Sintomi:

I timestamp scritti con Django Now(), auto_nowo auto_now_add vengono spostati quando il fuso orario dell'host SQL Server non è UTC.

Soluzione: Aggiorna a una versione attuale mssql-django . Il backend genera SQL Now() con riconoscimento del fuso orario, conserva gli offset datetimeoffset e legge i dati del fuso orario tramite zoneinfo e tzdata.

`AttributeError` quando si chiama `.explain()`

Sintomi:

AttributeError: ... explain_format ...

Soluzione: Aggiorna a una versione attuale mssql-django . I controlli backend spiegano i metadati per ogni versione supportata di Django.

Impossibile modificare AutoField

Sintomi:

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

Soluzione: SQL Server non supporta la modifica di un campo da o a AutoField. Creare un nuovo modello con il tipo di campo desiderato, eseguire la migrazione manuale dei dati e quindi eliminare la tabella precedente. Per soluzioni alternative, vedere Migrazioni di database con mssql-django.

La ridenominazione ha esito negativo con vincolo di chiave esterna

Sintomi:

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

Soluzione: SQL Server richiede l'eliminazione di vincoli di chiave esterna prima di rinominare le colonne. Usare SeparateDatabaseAndState nella migrazione. Per un esempio, vedere Migrazioni di database con mssql-django.

Problemi di codifica

Gli errori di codifica si verificano tipicamente nel percorso pyodbc quando pyodbc interpreta erroneamente i dati di carattere da SQL Server.

Errori di codifica Unicode

Sintomi:

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

Soluzione: Configurare la codifica pyodbc nel dizionario OPTIONS. Il percorso mssql-python ignora unicode_results.

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

Problemi di FreeTDS

FreeTDS richiede una configurazione specifica per pyodbc che differisce dal driver ODBC di Microsoft.

errore di host_is_server

Sintomi:

La connessione non riesce quando si usa FreeTDS senza specificare host_is_server.

Soluzione: impostare host_is_server su True quando si usa FreeTDS:

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

Per altre informazioni sulla configurazione freeTDS, vedere Opzioni di connessione per mssql-django.

Problemi del database di test

La creazione e la distruzione del database di test possono non riuscire a seconda del metodo di autenticazione.

Non è possibile creare un database di test con identità gestita

Sintomi:

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

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

Il test runner non riesce a creare o eliminare il database di test quando si usa l'autenticazione ActiveDirectoryMsi (identità gestita). Questa limitazione esiste perché:

Le credenziali dell'identità gestita vengono recuperate dall'ambiente host, ad esempio da Macchina virtuale di Azure e App Service.
L'esecutore dei test tenta di connettersi utilizzando le credenziali del database test durante la fase di pulizia finale.
L'identità gestita può essere concessa ai ruoli a livello di database, ma la creazione e l'eliminazione del database di test richiedono in genere autorizzazioni a livello di server che i test runner spesso non hanno.

Metodi di autenticazione interessati:

ActiveDirectoryMsi (identità gestita di Azure)
ActiveDirectoryServicePrincipal (se configurata solo nell'ambito del server)

Metodi di autenticazione supportati (funziona la creazione del database di test):

ActiveDirectoryPassword
ActiveDirectoryIntegrated
Autenticazione SQL (nome utente/password)

Compromessi dell'autenticazione negli ambienti di test

Method	Senza segreto	Funziona con la creazione/eliminazione automatica del database di test	Uso tipico
`ActiveDirectoryMsi`	Yes	In genere no (a meno che non vengano concessi diritti a livello di server)	carichi di lavoro di produzione ospitati su Azure
`ActiveDirectoryServicePrincipal`	No (segreto del client/certificato)	Dipende dai diritti a livello di server concessi	CI/CD con gestione esplicita delle identità
`ActiveDirectoryPassword`	No	Sì (con autorizzazioni SQL sufficienti)	Ambienti di sviluppo e ambienti CI controllati
Autenticazione SQL	No	Sì (con autorizzazioni SQL sufficienti)	Ambienti di test locali o isolati

Soluzioni:

Per lo sviluppo: usare il --keepdb flag per ignorare l'disinstallazione del database di test:
```
python manage.py test --keepdb
```

Per le pipeline CI/CD: creare preventivamente un database di test dedicato e concedere all'identità gestita le autorizzazioni 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: usare l'autenticazione SQL per gli ambienti di test o passare a ActiveDirectoryPassword per i test runner CI/CD.

Procedure di rollback

Quando una migrazione non riesce a metà del processo, utilizzare questa sequenza di rollback per tornare a uno stato stabile noto:

Interrompere le scritture dell'applicazione per evitare un'ulteriore deriva dello schema.

Esaminare lo stato della migrazione:

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

Esegui il rollback all'ultima migrazione riuscita nota:

python manage.py migrate <app_label> <previous_migration>

Se lo schema e la cronologia delle migrazioni divergono, correggere lo stato con attenzione con --fake solo dopo aver verificato lo schema effettivo del database.
Rieseguire prima le migrazioni in un ambiente di staging, quindi riprovare la produzione.

Importante

Per le migrazioni distruttive, ad esempio eliminazione, ridenominazione e modifica del tipo di colonna, eseguire un backup testato prima della distribuzione. Se il rollback tramite migrazione non è possibile, eseguire il ripristino dal backup e riapplicare le migrazioni convalidate.

Problemi relativi a Docker e contenitori

Le immagini container richiedono l'installazione esplicita di driver ODBC e dipendenze di build quando si usa il percorso pyodbc predefinito. Il percorso mssql-python non ha un'installazione separata di driver ODBC, ma ha comunque bisogno del runtime unixODBC, perché il backend importa pyodbc quando Django lo carica.

Driver ODBC non trovato nel contenitore

Sintomi:

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

Possibili cause e soluzioni:

Driver ODBC non installato nell'immagine del contenitore

Le immagini di base Slim o Alpine non includono il driver ODBC. Aggiungi il repository Microsoft APT e installa msodbcsql18 nel tuo Dockerfile quando usi pyodbc. Vedere Distribuire in App Service per un esempio completo di Dockerfile.
Pacchetto mancante unixodbc-dev

La pyodbc rotella è collegata con libodbc.so. Installare unixodbc-dev (Debian/Ubuntu) o unixODBC-devel (RHEL/Fedora) prima di installare pacchetti Python.
apt-get autoremove rimosso libgssapi-krb5-2 dopo l'installazione del driver

msodbcsql18 si carica libgssapi-krb5-2 in tempo reale senza dichiararlo come dipendenza. La libreria di solito arriva come dipendenza di curl, quindi purgando curl con --auto-remove, o eseguendo apt-get autoremove dopo, viene rimossa. L'immagine viene compilata senza errori, ma poi tutte le connessioni falliscono. Installa libgssapi-krb5-2 esplicitamente e non rimuovere automaticamente dopo l'installazione del driver.

Il driver 17 è stato segnalato come mancante quando è stata installata la versione 18

Sintomi:

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

L'errore indica la versione 17, ma odbcinst -q -d mostra la versione 18 registrata e dpkg -l msodbcsql18 come installata.

Causa: La versione 18 è registrata ma non si carica, quindi mssql-django torna alla versione 17, che non è installata. Il fallback riporta il secondo driver che ha provato, non quello che non ha funzionato.

Soluzione: installare libgssapi-krb5-2 e ricostruire. Vedi la nota precedente su autoremove per capire come la libreria viene a mancare.

Errore di caricamento modulo pyodbc in un container

Sintomi:

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

Causa: L'immagine non ha runtime unixODBC. mssql-django importa pyodbc quando Django carica il backend, quindi questo errore si verifica anche sul percorso mssql-python, prima che venga tentata qualsiasi connessione.

Soluzione: installare unixodbc (o unixodbc-dev).

Il driver mssql-python non si carica

Sintomi:

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

Causa: Il driver fornito con mssql-python richiede le librerie di runtime di Kerberos, che le immagini di base slim non includono.

Soluzione: installare libkrb5-3 e libgssapi-krb5-2.

pyodbc non riesce a creare immagini sottili

Sintomi:

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

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

Soluzione: installare le dipendenze di compilazione prima di pip install:

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

In alternativa, usare una compilazione a più fasi per mantenere l'immagine finale piccola:

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

Il contenitore non può connettersi a SQL Server

Sintomi:

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

Possibili cause e soluzioni:

Nome del servizio Docker Compose non usato come host

Quando si usa Docker Compose, impostare DB_HOST sul nome del servizio (ad esempio, db), non localhost o 127.0.0.1.

SQL Server contenitore non pronto

L'avvio del contenitore SQL Server richiede alcuni secondi. Aggiungere un controllo di integrità o un ritardo di avvio:

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

Conflitti di mappatura delle porte

Se un'altra istanza di SQL Server è in esecuzione nell'host, modificare la porta esposta ( ad esempio 1434:1433) e aggiornare di conseguenza la configurazione di Django.

Azure SQL ripristino da errori temporanei

Il mssql-django back-end rileva automaticamente le connessioni database SQL di Azure e Istanza gestita di SQL di Azure eseguendo query su SERVERPROPERTY('EngineEdition'). In caso di esecuzione su Azure SQL, il back-end ritenta le connessioni in caso di errori temporanei, ad esempio limiti di risorse temporanei o brevi interruzioni di rete.

È possibile ottimizzare questo comportamento con le connection_retries opzioni e connection_retry_backoff_time :

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

Queste impostazioni si applicano solo all'impostazione iniziale della connessione. Il back-end non ritenta le query non riuscite. Se una query non riesce a causa di un errore temporaneo dopo che la connessione è stata stabilita, l'eccezione viene propagata fino al codice dell'applicazione. Usare la logica di ripetizione dei tentativi a livello di applicazione , ad esempio django-retry-db o un middleware personalizzato, per la resilienza a livello di query.

Query lente e regressioni del piano di esecuzione

Questi problemi richiedono in genere l'analisi lato server insieme alla revisione delle query a livello di Django.

La query diventa più lenta o avvia il timeout

Sintomi:

Lo stesso set di query diventa più lento nel tempo o inizia a scadere dopo una distribuzione, una modifica dell'indice o un aggiornamento delle statistiche.

Possibili cause e soluzioni:

Iniziare con i report sulle prestazioni predefiniti

Per SQL Server e Istanza gestita di SQL di Azure, aprire Performance Dashboard in SQL Server Management Studio. Per database SQL di Azure aprire Informazioni dettagliate prestazioni query per database SQL di Azure. Questi strumenti sono in genere un primo passo migliore rispetto alle query DMV ad hoc perché consentono di individuare rapidamente query costose, tempi di attesa e saturazione delle risorse.
Regressione nel piano

Usa Query Store per trovare la query lenta e verificare se ha più piani di esecuzione. Inizia con le viste Query regredite e Query che consumano più risorse descritte in Procedure consigliate per il monitoraggio dei carichi di lavoro con Query Store.
Piano di esecuzione inefficiente

Apri un piano di esecuzione effettivo per l'istruzione e verifica la presenza di scansioni delle tabelle o degli indici, operazioni di ricerca di chiavi di grandi dimensioni, spill dell'hash o stime del numero di righe imprecise. Per informazioni generali, vedere Panoramica del piano di esecuzione.
Identificato il collo di bottiglia errato

Se la query non è limitata dalla CPU, usare le statistiche di attesa di Query Store e Identificare i colli di bottiglia per distinguere tra CPU, memoria, I/O del disco, blocchi e saturazione delle connessioni.
Correzione applicata nel livello errato

Applicare la correzione più piccola efficace: aggiungere o regolare indici, aggiornare le statistiche, ridurre le colonne e le righe selezionate o scrivere in batch di grandi dimensioni. Se è necessaria una mitigazione di emergenza, un amministratore del database può forzare temporaneamente un piano valido noto in Query Store mentre si corregge la causa radice.

Usare dbshell per eseguire query interattive

Il comando di gestione di dbshell Django apre una shell SQL interattiva connessa al database:

python manage.py dbshell

Il back-end usa sqlcmd quando si configura il driver ODBC Microsoft o isql quando si usa FreeTDS. Verifica che il comando sia nel PATH:

Windows: sqlcmd è incluso negli strumenti di SQL Server oppure è possibile scaricarlo separatamente.
Linux e macOS: eseguire l'installazione mssql-tools18 dal repository Microsoft.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-09-29

Risolvere i problemi relativi a mssql-django

Problemi di connessione

Il driver ODBC non è stato trovato sul percorso pyodbc

MSSQL-Python rifiuta un'opzione di connessione

La dipendenza da MSSQL-Python è troppo vecchia

Il fallback del driver 17 non si applica a mssql-python

Connessione rifiutata

Accesso non riuscito

Timeout della connessione

Problemi di migrazione

Problemi di SQL grezzo e GROUP BY

IndexError su GROUP BY con parametri con caratteri di escape %% e parametri reali

NotImplementedError per IntegerChoices nelle query GROUP BY non elaborate

Problemi di ricerca Regex

__regex oppure __iregex non restituisce righe

Cannot find ... dbo.REGEXP_LIKE

Problemi relativi a data e ora

Now() i valori vengono spostati quando USE_TZ=True

AttributeError quando si chiama .explain()

Impossibile modificare AutoField

La ridenominazione ha esito negativo con vincolo di chiave esterna

Problemi di codifica

Errori di codifica Unicode

Problemi di FreeTDS

errore di host_is_server

Problemi del database di test

Non è possibile creare un database di test con identità gestita

Compromessi dell'autenticazione negli ambienti di test

Procedure di rollback

Problemi relativi a Docker e contenitori

Driver ODBC non trovato nel contenitore

Il driver 17 è stato segnalato come mancante quando è stata installata la versione 18

Errore di caricamento modulo pyodbc in un container

Il driver mssql-python non si carica

pyodbc non riesce a creare immagini sottili

Il contenitore non può connettersi a SQL Server

Azure SQL ripristino da errori temporanei

Query lente e regressioni del piano di esecuzione

La query diventa più lenta o avvia il timeout

Usare dbshell per eseguire query interattive

Contenuti correlati

Commenti e suggerimenti

Risorse aggiuntive

`IndexError` su GROUP BY con parametri con caratteri di escape `%%` e parametri reali

`NotImplementedError` per `IntegerChoices` nelle query GROUP BY non elaborate

`regex` oppure `iregex` non restituisce righe

`Cannot find ... dbo.REGEXP_LIKE`

`Now()` i valori vengono spostati quando `USE_TZ=True`

`AttributeError` quando si chiama `.explain()`