Résoudre les problèmes liés à mssql-django

Diagnostiquez et résolvez les problèmes courants liés au mssql-django serveur principal pour SQL Server, Azure SQL Database, Azure SQL Managed Instance et la base de données SQL dans Microsoft Fabric.

mssql-django La version 2.0 prend en charge le chemin de pilote pyodbc par défaut et un chemin de pilote mssql-python en option d’adhésion. Pour plus d’informations, voir Sélectionner le pilote de base de données pour mssql-django.

Problèmes de connexion

Cette section décrit les erreurs de connexion les plus courantes et explique comment les résoudre.

Pilote ODBC introuvable dans le chemin d’accès de pyodbc

Symptômes :

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

Causes possibles et solutions :

  • Pilote ODBC non installé

    Installez le pilote Microsoft ODBC pour SQL Server lorsque vous utilisez le chemin pyodbc par défaut. Pour obtenir des liens de téléchargement, consultez Télécharger le pilote ODBC pour SQL Server. Le chemin mssql-python n’utilise pas de pilote ODBC installé en externe.

  • Plusieurs versions de pilotes installées

    Spécifiez le nom ou le chemin exact du pilote dans 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",
        },
    },
}

    Sur Linux, spécifiez le chemin complet :

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

  • Vérifier les pilotes installés

    • Sur Linux/macOS, exécutez odbcinst -q -d.
    • Sur Windows, vérifiez les sources de données ODBC dans les outils d’administration.

MSSQL-Python rejette une option de connexion

Symptômes :

Un alias défini dans "python_driver": "mssql_python" échoue pendant l’établissement de la connexion après avoir déplacé les mots-clés de chaîne de connexion pyodbc dans OPTIONS["extra_params"], avec l’un des messages d’erreur suivants :

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

Le nom du mot-clé dans le message est en minuscules, donc un mot-clé que vous avez écrit LongAsMax apparaît comme longasmax. ConnectionStringParseError ne fait pas partie de la hiérarchie des exceptions DB-API, donc Django ne la refait pas comme une django.db.utils erreur.

Causes possibles et solutions :

  • Mot-clé réservé à pyodbc dans extra_params

    Le chemin mssql-python valide extra_params par rapport à une liste de permis. DRIVER et APP sont réservés au conducteur et produisent le Reserved keyword formulaire. DSN, SERVERNAME, LongAsMax et les mots-clés propres à pyodbc tels que ColumnEncryption, WSID, AnsiNPW, Regional, QuotedId, UseFMTONLY, Current Language, Network Library, Description, Connect Timeout et Unknown keyword ne figurent pas dans la liste d’autorisation et génèrent la forme MARS_Connection. Supprimez le mot-clé, ou utilisez le chemin pyodbc par défaut pour un alias nécessitant cette option ODBC.

  • Option de pilote censée contrôler mssql-python

    Le chemin mssql-python ignore driver, dsn, host_is_server, et unicode_results. HOST et PORT deviennent SERVER=<server>,<port>, et un vide HOST devient localhost.

La dépendance à MSSQL-Python est trop ancienne

Symptômes :

Un alias qui définit "python_driver": "mssql_python" échoue lors de l’établissement de la connexion avec l’une de ces erreurs :

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

La deuxième forme signifie que le mssql_python module n’est pas du tout importable.

Solution : Installer mssql-python>=1.15.0. mssql-django La version 2.0 déclare mssql-python>=1.15.0, donc une normale pip install mssql-django résout une version compatible sur les plateformes supportées.

La solution de repli de Driver 17 ne s’applique pas à mssql-python

Symptômes :

Un alias qui définit "python_driver": "mssql_python" continue d’échouer même si Microsoft ODBC Driver 17 for SQL Server est installé.

Il n’y a pas d’erreur distinctive pour cette affaire. Le chemin mssql-python ignore silencieusement l’option driver , donc la connexion échoue avec l’erreur sous-jacente appliquée. Si vous déplacez plutôt le nom du pilote dans extra_params, vous obtenez une erreur Reserved keyword 'driver'. Voir mssql-python rejette une option de connexion.

Solution : Utiliser le chemin pyodbc par défaut si l’alias doit utiliser un pilote ODBC 17 installé en externe. Le chemin mssql-python ne revient pas au pilote 17, et il ignore cette driver option. Ce chemin n’a pas besoin d’un pilote ODBC installé séparément.

Connexion refusée

Symptômes :

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

Causes possibles et solutions :

  • TCP/IP non activé sur SQL Server

    • Ouvrez Gestionnaire de configuration SQL Server.
    • Sous SQL Server configuration réseau, activez TCP/IP.
    • Dans les propriétés TCP/IP, activez l’adresse IP utilisée pour la connexion.
    • Redémarrez le service SQL Server.

  • Pare-feu bloquant le port 1433

    • Vérifiez que les règles de pare-feu autorisent les connexions entrantes sur le port 1433.
    • Pour Azure SQL, ajoutez votre adresse IP cliente dans les paramètres de pare-feu du portail Azure.

  • Nom ou port du serveur incorrect

    Vérifiez les valeurs HOST et PORT de votre configuration.

Échec de la connexion

Symptômes :

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

Sur le chemin mssql-python :

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

Causes possibles et solutions :

  • Informations d’identification incorrectes

    Vérifiez le nom d’utilisateur et le mot de passe.

  • La base de données n’existe NAME pas

    Sur SQL Server, le chemin mssql-python affiche le même OperationalError message qu'un mauvais mot de passe, donc le message seul ne vous indique pas lequel vous avez frappé. Confirmez que la base de données existe avant de changer vos identifiants. Faites pointer NAME vers master pour tester la connexion de manière isolée : si la connexion fonctionne, les identifiants sont corrects et le problème vient de la base de données. Le chemin pyodbc rapporte ce cas séparément comme Cannot open database "<database>" requested by the login. The login failed. (4060).

    Azure SQL Database rapporte ce cas différemment. Le chemin mssql-python affiche Driver Error: General error; DDBC Error: [Microsoft][SQL Server]Cannot open server "<server>" requested by the login. The login failed. Le message nomme le serveur, mais le nom du serveur est correct. Vérifiez NAME à la place.

  • L’utilisateur n’existe pas

    Vérifiez que la connexion est mappée à un utilisateur dans la base de données cible.

  • Authentification SQL Server désactivée

    Activez l’authentification en mode mixte, ou utilisez Windows ou l’authentification Microsoft Entra.

Délai d’expiration de la connexion

Symptômes :

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

Causes possibles et solutions :

  • Latence du réseau

    Augmentez connection_timeout dans OPTIONS.

  • Azure SQL Database serverless avec auto-pause activée

    Une base de données en pause automatique reprend lors de la première tentative de connexion, et cette tentative peut échouer avec l’erreur 40613 pendant que la base de données reprend. Réglez connection_timeout au moins 60 et réessayez la première connexion. Pour plus d’informations, voir Azure SQL Database serverless et Auto-pause et auto-reprise.

  • Serveur surchargé

    Augmenter connection_retries et connection_retry_backoff_time.

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

Problèmes de migration

Ces erreurs se produisent pendant les opérations de migration de Django sur SQL Server.

Problèmes de SQL brut et de GROUP BY

Ces erreurs surviennent lorsque des requêtes brutes ou annotées avec une clause GROUP BY passent par l’étape de réécriture des espaces réservés du backend.

IndexError sur GROUP BY avec %% paramètres échappés et réels

Symptômes :

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

La requête fonctionne sans la GROUP BY clause et sans le littéral échappé %% , mais échoue lorsque les deux sont présents à côté d’un paramètre réel %s .

Solution : Passer à une version actuelle mssql-django . Le backend réduit le régex de réécriture de substitut à %% et %s seulement, de sorte que les littéraux échappés %% sont conservés mot pour mot et aucun substitut fantôme n’est injecté.

NotImplementedError pour IntegerChoices dans les requêtes brutes GROUP BY

Symptômes :

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

La même valeur d’enum fonctionne dans les requêtes ORM et dans les requêtes brutes sans GROUP BY, mais échoue lorsqu’elle est passée comme paramètre à une requête brute contenant une GROUP BY clause.

Solution : Passer à une version actuelle mssql-django . Le backend utilise isinstance pour effectuer des vérifications du type des paramètres dans le chemin GROUP BY, de sorte que IntegerChoices (une sous-classe de int) est correctement lié. bool lie toujours bit, et int simple reste inchangé.

Problèmes de recherche de régex

__regex ou __iregex ne retourne aucune ligne

Symptômes : La requête s’exécute sans erreur et renvoie un ensemble de résultats vide, même si les lignes correspondent au motif.

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

Cause : dbo.REGEXP_LIKE ignore littéralement l’espace blanc dans le motif. Le motif est interprété comme s’il s’agissait de ^Widget\d+$, auquel aucune valeur contenant un espace ne peut correspondre. Rien ne s’affiche, donc le résultat vide ressemble à un problème de données.

Solution : Écrire des espaces blancs comme échappement ou classe de caractère :

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

Cannot find ... dbo.REGEXP_LIKE

Symptômes :

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

Sur le chemin 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.

Cause : L’assembleur CLR n’est pas installé dans la base de données que vous interrogez. C’est installé par base de données, pas par serveur.

Solution : Exécutez python manage.py install_regex_clr <database> sur cette base de données. Relancez-la après avoir supprimé puis recréé une base de données. Voir Configurer les recherches par regex.

Problèmes de date et d’heure

Now() les valeurs sont décalées lorsque USE_TZ=True

Symptômes :

Horodatages écrits avec Django Now(), auto_nowou auto_now_add sont décalés lorsque le fuseau horaire de l'hôte SQL Server n'est pas UTC.

Solution : Passer à une version actuelle mssql-django . Le back-end génère du SQL Now() prenant en charge les fuseaux horaires, préserve les décalages de datetimeoffset et lit les données de fuseau horaire via zoneinfo et tzdata.

AttributeError lors de l'appel de .explain()

Symptômes :

AttributeError: ... explain_format ...

Solution : Passer à une version actuelle mssql-django . Les gestionnaires backend expliquent les métadonnées pour chaque version prise en charge de Django.

Impossible de modifier AutoField

Symptômes :

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

Solution : SQL Server ne prend pas en charge la modification d'un champ depuis ou vers AutoField. Créez un modèle avec le type de champ souhaité, migrez les données manuellement, puis supprimez l’ancienne table. Pour obtenir des solutions de contournement, consultez migrations de base de données avec mssql-django.

Le changement de nom échoue avec la contrainte de clé étrangère

Symptômes :

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

Solution : SQL Server nécessite la suppression de contraintes de clé étrangère avant de renommer des colonnes. Utilisez SeparateDatabaseAndState dans votre migration. Pour obtenir un exemple, consultez migrations de base de données avec mssql-django.

Problèmes d’encodage

Les erreurs d’encodage surviennent généralement dans le chemin pyodbc lorsque pyodbc interprète mal les données de type caractère provenant de SQL Server.

Erreurs d’encodage Unicode

Symptômes :

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

Solution : Configurez l’encodage pyodbc dans le dictionnaire OPTIONS. Le chemin mssql-python ignore unicode_results.

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

Problèmes FreeTDS

FreeTDS nécessite une configuration spécifique à pyodbc qui diffère du pilote ODBC de Microsoft.

Erreur host_is_server

Symptômes :

La connexion échoue lors de l’utilisation de FreeTDS sans spécifier host_is_server.

Solution : définissez host_is_server sur True lorsque vous utilisez FreeTDS :

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

Pour plus d’informations sur la configuration de FreeTDS, consultez les options de connexion pour mssql-django.

Problèmes de base de données de test

La création et la destruction des bases de données de test peuvent échouer en fonction de votre méthode d’authentification.

Impossible de créer une base de données de test avec une identité managée

Symptômes :

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

Ou:

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

L’exécuteur de tests ne parvient pas à créer ni à détruire la base de données de test lorsque vous utilisez l’authentification par ActiveDirectoryMsi (identité managée). Cette limitation existe, car :

  • Les informations d’identification d’identité managée sont obtenues à partir de l’environnement hôte (par exemple, Azure machine virtuelle et App Service).

  • L’exécuteur de tests tente de se connecter à l’aide des identifiants de la base de données test lors de l’étape de nettoyage.

  • L’identité managée peut recevoir des rôles au niveau de la base de données, mais la création et la suppression de bases de données de test nécessitent généralement des autorisations au niveau du serveur que les exécuteurs de test n’ont pas souvent.

Méthodes d’authentification affectées :

  • ActiveDirectoryMsi(identité managée Azure)
  • ActiveDirectoryServicePrincipal (lorsqu’il est configuré uniquement au niveau du serveur)

Méthodes d’authentification prises en charge (la création de base de données de test fonctionne) :

  • ActiveDirectoryPassword
  • ActiveDirectoryIntegrated
  • Authentification SQL (nom d’utilisateur/mot de passe)

Compromis d’authentification pour les environnements de test

Method Sans secret Fonctionne avec la création/suppression automatique de la base de données de test Utilisation classique
ActiveDirectoryMsi Yes Généralement non (sauf si les droits au niveau du serveur sont accordés) charges de travail de production hébergées sur Azure
ActiveDirectoryServicePrincipal Non (client secret/certificat) Dépend des droits accordés au niveau du serveur CI/CD avec gestion explicite des identités
ActiveDirectoryPassword Non Oui (avec des autorisations SQL suffisantes) Environnements CI de développement et contrôlés
Authentification SQL Non Oui (avec des autorisations SQL suffisantes) Environnements de test locaux ou isolés

Solutions :

  • Pour le développement : Utilisez l’indicateur --keepdb pour ignorer la déchirure de base de données de test :

    python manage.py test --keepdb

  • Pour les pipelines CI/CD : créez au préalable une base de données de test dédiée et accordez les autorisations à l’identité managée CREATE TABLE et à 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];

  • Alternative : utilisez l’authentification SQL pour les environnements de test, ou passez à ActiveDirectoryPassword pour les runners de test CI/CD.

Procédures de restauration

Lorsqu’une migration échoue en partie, utilisez cette séquence de restauration pour revenir à un état correct connu :

  1. Arrêtez les écritures d’applications pour éviter une dérive de schéma supplémentaire.

  2. Inspectez l’état de migration :

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

  3. Revenez à la dernière migration correcte connue :

    python manage.py migrate <app_label> <previous_migration>

  4. Si le schéma et l’historique de migration diffèrent, réparez l’état avec soin --fake uniquement après avoir vérifié le schéma de base de données réel.

  5. Réexécutez d’abord les migrations dans un environnement intermédiaire, puis réessayez la production.

Important

Pour les migrations destructrices telles que la suppression, le renommage et les modifications de type de colonne, effectuez une sauvegarde testée avant le déploiement. Si la restauration par migration n’est pas possible, restaurez à partir de la sauvegarde et réappliquez les migrations validées.

Problèmes liés à Docker et au conteneur

Les images de conteneur nécessitent une installation explicite du pilote ODBC et des dépendances de compilation lorsque vous utilisez la méthode pyodbc par défaut. Le chemin mssql-python n’a pas d’installation de pilote ODBC séparé, mais il a toujours besoin de l’exécution unixODBC, car le backend importe pyodbc quand Django le charge.

Pilote ODBC introuvable dans le conteneur

Symptômes :

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

Causes possibles et solutions :

  • Pilote ODBC non installé dans l’image conteneur

    Les images de base Slim ou Alpine n’incluent pas le pilote ODBC. Ajoutez le dépôt APT Microsoft et installez msodbcsql18 dans votre Dockerfile lorsque vous utilisez pyodbc. Consultez Déployer sur App Service pour obtenir un exemple complet de Dockerfile.

  • Package manquant unixodbc-dev

    Le wheel pyodbc est lié à libodbc.so. Installez unixodbc-dev (Debian/Ubuntu) ou unixODBC-devel (RHEL/Fedora) avant d’installer des packages Python.

  • apt-get autoremove Supprimé libgssapi-krb5-2 après l’installation du pilote

    msodbcsql18 se charge libgssapi-krb5-2 à l’exécution sans le déclarer comme une dépendance. La bibliothèque arrive généralement comme une dépendance de curl, donc purger curl avec --auto-remove, ou exécuter apt-get autoremove ensuite la supprime. L’image se génère correctement, puis toutes les connexions échouent. Installez libgssapi-krb5-2 de manière explicite, et ne le supprimez pas automatiquement après l’installation du pilote.

Le pilote 17 a été signalé comme manquant lors de l’installation de la version 18

Symptômes :

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

L’erreur indique la version 17, mais odbcinst -q -d montre la version 18 enregistrée et dpkg -l msodbcsql18 installée.

Cause : La version 18 est enregistrée mais ne se charge pas, donc mssql-django revient à la version 17, qui n’est pas installée. Le mécanisme de repli signale le pilote qu’il a essayé en deuxième, et non celui qui a échoué.

Solution : installer libgssapi-krb5-2 et reconstruire. Voir la note d’autosuppression ci-dessus pour savoir comment la bibliothèque disparaît.

Erreur de chargement du module pyodbc dans un conteneur

Symptômes :

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

Cause: L’image ne contient pas l’environnement d’exécution unixODBC. mssql-django importe pyodbc lorsque Django charge le backend, donc cette erreur se produit aussi sur le chemin mssql-python, avant qu’une connexion ne soit tentée.

Solution : Installer unixodbc (ou unixodbc-dev).

Le pilote mssql-python ne se charge pas

Symptômes :

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

Cause : Le pilote fourni avec mssql-python a besoin des bibliothèques d’exécution Kerberos, que les images de base allégées n’incluent pas.

Solution : installer libkrb5-3 et libgssapi-krb5-2.

pyodbc ne parvient pas à générer sur des images slim

Symptômes :

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

Ou:

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

Solution : Installez les dépendances de build avant pip install:

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

Vous pouvez également utiliser une build à plusieurs étapes pour conserver la petite image finale :

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

Le conteneur ne peut pas se connecter à SQL Server

Symptômes :

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

Causes possibles et solutions :

  • Nom du service Docker Compose non utilisé en tant qu’hôte

    Lors de l’utilisation de Docker Compose, définissez DB_HOST le nom du service (par exemple, dbnon localhost ou 127.0.0.1.

  • SQL Server conteneur non prêt

    Le conteneur SQL Server prend plusieurs secondes pour démarrer. Ajoutez un délai de contrôle d’intégrité ou de démarrage :

    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

  • Conflits de mappage de ports

    Si une autre instance de SQL Server s’exécute sur l’hôte, modifiez le port exposé (par exemple1434:1433) et mettez à jour votre configuration Django en conséquence.

Azure SQL récupération après erreur transitoire

Le mssql-django serveur principal détecte automatiquement les connexions Azure SQL Database et Azure SQL Managed Instance en interrogeant SERVERPROPERTY('EngineEdition'). Lors de l’utilisation d’Azure SQL, le backend réessaie d’établir la connexion en cas d’erreurs transitoires (telles que des limitations temporaires de ressources ou de brèves interruptions du réseau).

Vous pouvez régler ce comportement avec les options connection_retries et connection_retry_backoff_time :

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

Ces paramètres s’appliquent uniquement à l’établissement de connexion initial. Le back-end n’effectue pas de nouvelles tentatives de requêtes ayant échoué. Si une requête échoue avec une erreur temporaire après l’établissement de la connexion, l’exception se propage au code de votre application. Utilisez la logique de nouvelle tentative au niveau de l’application (par exemple, django-retry-db ou un intergiciel personnalisé) pour la résilience au niveau des requêtes.

Requêtes lentes et régressions de plan

Ces problèmes nécessitent généralement une analyse côté serveur, ainsi que la révision des requêtes au niveau de Django.

La requête devient plus lente ou finit par expirer

Symptômes :

Le même ensemble de requêtes devient plus lent au fil du temps, ou commence à dépasser le délai d’exécution après un déploiement, une modification d’index ou une mise à jour des statistiques.

Causes possibles et solutions :

  • Commencer par des rapports de performances intégrés

    Pour SQL Server et Azure SQL Managed Instance, ouvrez le tableau de bord des performances dans SQL Server Management Studio. Pour Azure SQL Database, ouvrez Query Performance Insight pour Azure SQL Database. Ces outils sont généralement une meilleure étape que les requêtes DMV ad hoc, car elles font rapidement apparaître des requêtes coûteuses, des attentes et une pression sur les ressources.

  • Régression du plan

    Utilisez Magasin des requêtes pour rechercher la requête lente et vérifier s’il a plusieurs plans. Commencez par les requêtes régressées et les vues Principales requêtes consommatrices de ressourcesdécrites dans les meilleures pratiques pour surveiller les charges de travail avec Magasin des requêtes.

  • Plan d’exécution inefficace

    Ouvrez un plan d’exécution réel pour l’instruction et recherchez des analyses de table ou d’index, des recherches importantes, des dépassements de hachage ou des estimations de lignes inexactes. Pour plus d’informations, consultez Vue d’ensemble du plan d’exécution.

  • Goulot d’étranglement incorrect identifié

    Si la requête n'est pas liée au processeur, utilisez Magasin des requêtes statistiques d'attente et identifiez les goulots d'étranglement pour distinguer le processeur, la mémoire, les E/S de disque, le blocage et la pression de connexion.

  • Correction appliquée dans la couche incorrecte

    Appliquez le plus petit correctif efficace : ajoutez ou ajustez des index, mettez à jour les statistiques, réduisez les colonnes et lignes sélectionnées ou les écritures volumineuses par lots. Si vous avez besoin d’une mesure d’atténuation d’urgence, un DBA peut temporairement forcer un plan connu comme étant fiable dans le Magasin des requêtes, le temps que vous corrigiez la cause racine.

Utiliser dbshell pour les requêtes interactives

La commande de gestion de dbshell Django ouvre un interpréteur de commandes SQL interactif connecté à votre base de données :

python manage.py dbshell

Le serveur principal utilise sqlcmd lorsque vous configurez le pilote ODBC Microsoft, ou isql lorsque vous utilisez FreeTDS. Vérifiez que l’outil se trouve sur votre PATH :

  • Windows : sqlcmd est inclus dans SQL Server outils, ou vous pouvez le télécharger séparément.
  • Linux et macOS : Installer mssql-tools18 à partir du référentiel Microsoft.

Contenu connexe

  • Last updated on