Řešení potíží s mssql-django

Diagnostika a řešení běžných problémů s back-endem mssql-django pro SQL Server, Azure SQL Database, Azure SQL Managed Instance a databází SQL v Microsoft Fabric

mssql-django Verze 2.0 podporuje výchozí cestu ovladače pyodbc a opt-in cestu ovladače mssql-python. Pro více informací viz Vybrat ovladač databáze pro mssql-django.

Problémy s připojením

Tato část se věnuje nejběžnějším chybám připojení a jejich řešení.

ODBC driver nebyl nalezen na cestě pyodbc

Příznaky:

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

Možné příčiny a řešení:

• Ovladač ODBC není nainstalován.

  Nainstalujte Microsoft ODBC ovladač pro SQL Server, když použijete výchozí cestu pyodbc. Odkazy ke stažení naleznete v tématu Stažení ovladače ODBC pro SQL Server. Cesta mssql-python nepoužívá externě nainstalovaný ODBC ovladač.

• Nainstalovaných více verzí ovladačů

  Zadejte přesný název nebo cestu ovladače v 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",
          },
      },
  }
  

  V Linuxu zadejte úplnou cestu:

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

• Kontrola nainstalovaných ovladačů

  • V Linuxu nebo macOS spusťte odbcinst -q -dpříkaz .
  • Na Windows zkontrolujte zdroje dat ODBC v nástrojích pro správu.

mssql-python odmítá možnost připojení

Příznaky:

Alias, který nastaví "python_driver": "mssql_python" , selže při navazování spojení poté, co přesunete klíčová slova z řetězce spojení pyodbc do OPTIONS["extra_params"], s jednou z těchto chyb:

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

Název klíčového slova ve zprávě je malým písmenem, takže klíčové slovo, které jste napsali jako , LongAsMax se objeví jako longasmax. ConnectionStringParseError není součástí hierarchie DB-API výjimek, takže Django to nepřebaluje jako chybu django.db.utils .

Možné příčiny a řešení:

• Klíčové slovo pouze pro pyodbc v extra_params

  Cesta mssql-python ověřuje extra_params vůči seznamu povolených položek. DRIVERa APP jsou vyhrazeny pro řidiče a vytvářejí formulář.Reserved keyword DSN, SERVERNAME, MARS_Connection a klíčová slova jen pro pyodbc, jako jsou ColumnEncryption, LongAsMax, WSID, AnsiNPW, QuotedId, Regional, UseFMTONLY, Current Language, Description, Network Library a Connect Timeout, nejsou na seznamu povolených a mají podobu Unknown keyword. Odstraňte klíčové slovo, nebo použijte výchozí cestu pyodbc pro alias, který potřebuje možnost ODBC.

• Volba ovladače určená k ovládání mssql-python

  Cesta mssql-python ignoruje driver, dsn, host_is_server a unicode_results. HOST a PORT se stanou SERVER=<server>,<port> a prázdné HOST se stane localhost.

Závislost mssql-python je příliš stará

Příznaky:

Alias, který nastavuje "python_driver": "mssql_python" , selže při navázání spojení s jednou z těchto chyb:

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

Druhá forma znamená, že modul není vůbec importovatelný mssql_python .

Řešení: Nainstalovat mssql-python>=1.15.0. mssql-django 2.0 určuje mssql-python>=1.15.0, takže běžný pip install mssql-django na podporovaných platformách najde kompatibilní verzi.

Záložní mechanismus u ovladače 17 se nepoužije pro mssql-python

Příznaky:

Alias, který nastavuje "python_driver": "mssql_python", stále selže, i když je nainstalovaný Microsoft ODBC Driver 17 pro SQL Server.

V tomto případě není žádná výrazná chyba. Větev mssql-python možnost driver tiše ignoruje, takže připojení selže s příslušnou podkladovou chybou. Pokud jste místo toho přesunuli jméno řidiče do extra_params, zobrazí se chyba Reserved keyword 'driver'. Viz mssql-python odmítá možnost připojení.

Řešení: Použijte výchozí cestu pyodbc, pokud alias musí používat externě nainstalovaný ODBC ovladač 17. Cesta mssql-python se nevrací zpět k ovladači 17 a tuto možnost ignoruje driver . Tato cesta nepotřebuje samostatně nainstalovaný ODBC ovladač.

Odmítnuté připojení

Příznaky:

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

Možné příčiny a řešení:

• Na SQL Server není povolený protokol TCP/IP

  • Otevřete nástroj SQL Server Configuration Manager.
  • V části SQL Server Konfigurace sítě povolte protokol TCP/IP.
  • Ve vlastnostech protokolu TCP/IP aktivujte IP adresu použitou pro připojení.
  • Restartujte službu SQL Server.

• Brána firewall blokující port 1433

  • Ověřte, že pravidla brány firewall povolují příchozí připojení na portu 1433.
  • Pro Azure SQL přidejte IP adresu klienta do nastavení brány firewall portálu Azure.

• Nesprávný název serveru nebo port

  Ověřte hodnoty HOST a PORT ve své konfiguraci.

Přihlášení se nezdařilo.

Příznaky:

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

Na cestě mssql-python:

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

Možné příčiny a řešení:

• Nesprávné přihlašovací údaje

  Ověřte uživatelské jméno a heslo.

• Databáze v NAME neexistuje

  V SQL Serveru větev mssql-python vyvolá stejné OperationalError se stejnou zprávou jako při zadání chybného hesla, takže ze samotné zprávy nepoznáte, na kterou z těchto situací jste narazili. Ověřte si, že databáze existuje, než změníte přihlašovací údaje. Nasměrujte NAME na master, abyste otestovali přihlášení samostatně: pokud se připojení podaří, přihlašovací údaje jsou správné a problém je v databázi. Pyodbc path tento případ hlásí samostatně jako Cannot open database "<database>" requested by the login. The login failed. (4060).

  Azure SQL Database tento případ popisuje jinak. Větev mssql-python vyvolá Driver Error: General error; DDBC Error: [Microsoft][SQL Server]Cannot open server "<server>" requested by the login. The login failed. V hlášení je uveden název serveru, ale název serveru je v pořádku. Místo toho zkontroluj NAME .

• Uživatel neexistuje.

  Ověřte, že je přihlášení namapované na uživatele v cílové databázi.

• SQL Server ověřování zakázáno

  Povolte ověřování ve smíšeném režimu nebo použijte ověřování Windows nebo Microsoft Entra.

Časový limit připojení vypršel

Příznaky:

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

Možné příčiny a řešení:

• Latence sítě

  Zvyšte connection_timeout v nabídce MOŽNOSTI.

• Serverless Azure SQL Database s povoleným automatickým pozastavením

  Automaticky pozastavená databáze se obnoví při prvním pokusu o připojení a tento pokus může selhat s chybou 40613, zatímco databáze pokračuje. Nastavte connection_timeout alespoň 60 a zkuste znovu první připojení. Další informace najdete v tématech Azure SQL Database serverless a Automatické pozastavení a automatické obnovení.

• Server přetížený

  Zvýšit connection_retries a connection_retry_backoff_time.

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

Problémy s migrací

K těmto chybám dochází během operací migrace Django proti SQL Server.

Problémy s RAW SQL a GROUP BY

K těmto chybám dochází, když nezpracované nebo anotované dotazy s klauzulí GROUP BY projdou krokem backendu pro přepisování zástupných symbolů.

IndexError v klauzuli GROUP BY s escapovanými %% a skutečnými parametry

Příznaky:

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

Dotaz funguje bez klauzule GROUP BY i bez escapovaného %% literálu, ale selhává, když jsou oba přítomny spolu s reálným %s parametrem.

Řešení: Upgradujte na mssql-django aktuální verzi. Backend omezuje regex pro přepisování zástupných symbolů pouze na %% a %s, takže escapované literály %% zůstávají zachovány doslovně a nevkládají se žádné falešné zástupné symboly.

NotImplementedError pro IntegerChoices v surových dotazech GROUP BY

Příznaky:

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

Stejná hodnota enum funguje v ORM dotazech i v surových dotazech bez GROUP BY, ale selže, když je předán jako parametr do surového dotazu obsahujícího klauzuli GROUP BY .

Řešení: Upgradujte na mssql-django aktuální verzi. Backend používá isinstance ke kontrole typů parametrů v rámci cesty GROUP BY, takže se IntegerChoices (podtřída int) správně naváže. bool se stále trochu váže bit, a obyčejné int zůstává nezměněné.

Problémy s regex vyhledáváním

__regex nebo __iregex nevrací žádné řádky

Příznaky: Dotaz běží bez chyby a vrací prázdnou množinu výsledků, i když řádky odpovídají vzoru.

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

Příčina: dbo.REGEXP_LIKE ignoruje doslova mezeru ve vzoru. Vzor je shodován, jako by byl ^Widget\d+$, což žádná hodnota obsahující mezeru nemůže splnit. Nic se nevyvolá, takže prázdný výsledek vypadá jako datový problém.

Řešení: Zapište prázdný znak jako escape sekvenci nebo třídu znaků:

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

Cannot find ... dbo.REGEXP_LIKE

Příznaky:

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

Na cestě 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.

Příčina: CLR assembly není nainstalován v databázi, kterou dotazujete. Instaluje se to podle databáze, ne podle serveru.

Řešení: Spusťte python manage.py install_regex_clr <database> proti této databázi. Znovu ho spusťte po odložení a znovuvytvoření databáze. Viz Nastavení vyhledávání pomocí regulárních výrazů.

Problémy s datem a časem

hodnoty Now() jsou posunuty, když USE_TZ=True

Příznaky:

Časová razítka zapsaná pomocí Django Now(), auto_now nebo auto_now_add jsou posunutá, pokud časové pásmo hostitele SQL Serveru není nastaveno na UTC.

Řešení: Upgradujte na mssql-django aktuální verzi. Backend generuje SQL s vědomím Now() časových pásem, uchovává offsety datetimeoffset a čte data časových pásem přes zoneinfo a tzdata.

AttributeError při volání .explain()

Příznaky:

AttributeError: ... explain_format ...

Řešení: Upgradujte na mssql-django aktuální verzi. Backend zpracovává metadata EXPLAIN pro každou podporovanou verzi Django.

Nelze změnit automatické pole

Příznaky:

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

Řešení: SQL Server nepodporuje změnu pole z nebo do AutoField. Vytvořte nový model s požadovaným typem pole, migrujte data ručně a potom zahoďte starou tabulku. Alternativní řešení najdete v tématu Migrace databází pomocí mssql-django.

Přejmenování selže kvůli omezení cizího klíče

Příznaky:

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

Řešení: SQL Server před přejmenováním sloupců vyžaduje vyřazení omezení cizího klíče. Použijte SeparateDatabaseAndState při migraci. Příklad najdete v tématu Migrace databází s mssql-django.

Problémy s kódováním

Chyby kódování se obvykle vyskytují na cestě pyodbc, když pyodbc špatně interpretuje znaková data ze SQL Server.

Chyby kódování Unicode

Příznaky:

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

Řešení: Nastavte pyodbc kódování ve slovníku OPTIONS . Cesta mssql-python ignoruje unicode_results.

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

Problémy s freeTDS

FreeTDS vyžaduje konfiguraci specifickou pro pyodbc, která se liší od ovladače Microsoft ODBC.

Chyba host_is_server

Příznaky:

Připojení selže při použití FreeTDS bez zadání host_is_server.

Řešení: Nastavte host_is_server na True , když používáte FreeTDS:

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

Další informace o konfiguraci FreeTDS naleznete v tématu Možnosti připojení pro mssql-django.

Problémy s testovací databází

Vytvoření a zničení testovací databáze může selhat v závislosti na metodě ověřování.

Nejde vytvořit testovací databázi se spravovanou identitou

Příznaky:

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

Or:

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

Při použití ověřování pomocí ActiveDirectoryMsi (spravované identity) se spouštěči testů nepodaří vytvořit ani odstranit testovací databázi. Toto omezení existuje, protože:

• Přihlašovací údaje spravované identity se získávají z hostitelského prostředí (například z virtuálního počítače Azure a ze služby App Service).

• Spouštěč testů se během ukončování pokusí připojit pomocí přihlašovacích údajů k databázi test.

• Spravované identitě je možné udělit role na úrovni databáze, ale vytvoření a odstranění testovací databáze obvykle vyžaduje oprávnění na úrovni serveru, která testovací spouštěče často nemají.

Ovlivněné metody ověřování:

• ActiveDirectoryMsi (spravovaná identita Azure)
• ActiveDirectoryServicePrincipal (pouze při konfiguraci na úrovni serveru)

Podporované metody ověřování (funguje vytváření testovací databáze):

• ActiveDirectoryPassword
• ActiveDirectoryIntegrated
• Ověřování SQL (uživatelské jméno a heslo)

Kompromisy ověřování pro testovací prostředí

Metoda	Bez tajemství	Funguje s automatickým vytvářením a odstraňováním testovací databáze.	Typické použití
ActiveDirectoryMsi	Yes	Obvykle ne (pokud nejsou udělena práva na úrovni serveru).	produkční úlohy hostované Azure
ActiveDirectoryServicePrincipal	Ne (tajný klíč klienta nebo certifikát)	Závisí na udělených právech na úrovni serveru.	CI/CD s explicitní správou identit
ActiveDirectoryPassword	No	Ano (s dostatečnými oprávněními SQL)	Vývojová a řízená prostředí CI
Ověřování SQL	No	Ano (s dostatečnými oprávněními SQL)	Místní nebo izolovaná testovací prostředí

Řešení:

• Pro vývoj: Použijte příznak --keepdb, chcete-li přeskočit odstranění testovací databáze:

  python manage.py test --keepdb
  

• Pro CI/CD kanály: Předem vytvořte vyhrazenou testovací databázi a udělte spravované identitě oprávnění CREATE TABLE a 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: Pro testovací prostředí použijte ověřování SQL Serveru nebo přejděte na ActiveDirectoryPassword pro spouštěče testů CI/CD.

Postupy vrácení zpět

Pokud migrace v průběhu selže, použijte tento postup vrácení zpět pro návrat do známého funkčního stavu:

1. Zastavte zápisy aplikací, abyste se vyhnuli dalším posunům schématu.

2. Kontrola stavu migrace:

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

3. Vraťte se k poslední známé dobré migraci:

   python manage.py migrate <app_label> <previous_migration>
   

4. Pokud se schéma a historie migrací rozcházejí, opravte stav opatrně pomocí --fake až po ověření skutečného schématu databáze.

5. Nejprve znovu spusťte migrace v testovacím prostředí a potom to zkuste znovu v produkci.

Important

V případě destruktivních migrací, jako je vyřazení, přejmenování a změny typu sloupce, proveďte před nasazením otestované zálohování. Pokud není možné vrátit změny pomocí migrace, obnovte systém ze zálohy a znovu použijte ověřené migrace.

Problémy s Dockerem a kontejnerem

Obrazy kontejneru vyžadují explicitní instalaci ODBC ovladačů a buildovací závislosti, když použijete výchozí cestu pyodbc. Varianta mssql-python nevyžaduje samostatnou instalaci ovladače ODBC, ale stále vyžaduje běhové prostředí unixODBC, protože backend při načítání v Djangu importuje pyodbc.

Ovladač ODBC nebyl v kontejneru nalezen.

Příznaky:

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

Možné příčiny a řešení:

• Ovladač ODBC není nainstalovaný v imagi kontejneru

  Základní obrazy Slim nebo Alpine neobsahují ovladač ODBC. Přidej Microsoft APT repozitář a nainstaluj msodbcsql18 ho do svého Dockerfile, když používáš pyodbc. Kompletní příklad souboru Dockerfile najdete v tématu Nasazení do služby App Service .

• Chybějící unixodbc-dev balíček

  pyodbc wheel je linkován proti libodbc.so. Před instalací balíčků Python nainstalujte unixodbc-dev (Debian/Ubuntu) nebo unixODBC-devel (RHEL/Fedora).

• apt-get autoremovePo instalaci ovladače jsem byl odstraněn libgssapi-krb5-2

  msodbcsql18 načítá libgssapi-krb5-2 za běhu, aniž by ho deklaroval jako závislost. Knihovna se obvykle nainstaluje jako závislost curl, takže jejím vyčištěním pomocí --auto-remove nebo následným spuštěním apt-get autoremove se odstraní. Bitová kopie se sestaví bez chyb a pak všechna připojení selžou. Instalujte libgssapi-krb5-2 explicitně a neodstraňujte automaticky po instalaci ovladače.

Ovladač 17 byl nahlášen jako nezvěstný, když jste instalovali verzi 18

Příznaky:

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

V chybové zprávě je uvedena verze 17, ale odbcinst -q -d ukazuje, že je zaregistrována verze 18, a dpkg -l msodbcsql18 ukazuje, že je nainstalovaná.

Příčina: Verze 18 je zaregistrována, ale nepodařilo se ji načíst, takže mssql-django se vrací k verzi 17, která není nainstalovaná. Záložní mechanismus nahlásí ovladač, který zkusil jako druhý, ne ten, který selhal.

Řešení: Nainstalovat a znovu postavit libgssapi-krb5-2 . Viz předchozí poznámku k automatickému odstraňování, kde je vysvětleno, jak knihovna zmizí.

Chyba při načítání modulu pyodbc v kontejneru

Příznaky:

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

Příčina: Bitová kopie neobsahuje běhové prostředí unixODBC. mssql-django importuje pyodbc, když Django načítá backend, takže tato chyba se objeví i na cestě mssql-python, ještě před pokusem o připojení.

Řešení: Instalace unixodbc (nebo unixodbc-dev).

ovladač mssql-python se nenačte

Příznaky:

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

Příčina: Ovladač dodávaný s mssql-python potřebuje knihovny běhového prostředí Kerberos, které odlehčené základní obrazy neobsahují.

Řešení: Nainstalovat libkrb5-3 a libgssapi-krb5-2.

Pyodbc se nepovede vytvářet na tenkých obrázcích

Příznaky:

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

Or:

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

Řešení: Nainstalujte závislosti pro sestavení před pip install:

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

Případně můžete použít vícefázové sestavení, abyste zachovali konečnou image v malém rozsahu:

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

Kontejner se nemůže připojit k SQL Server

Příznaky:

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

Možné příčiny a řešení:

• Název služby Docker Compose se nepoužívá jako hostitel

  Pokud používáte Docker Compose, nastavte DB_HOST na název služby (například db), ne localhost nebo 127.0.0.1.

• SQL Server kontejner není připravený

  Spuštění kontejneru SQL Server trvá několik sekund. Přidejte kontrolu stavu nebo zpoždění spuštění:

  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
  

• Konflikty mapování portů

  Pokud na hostiteli běží jiná instance SQL Server, změňte vystavený port (například1434:1433) a odpovídajícím způsobem aktualizujte konfiguraci Django.

Azure SQL obnovení po přechodných chybách

Backend mssql-django automaticky rozpozná připojení ke službám Azure SQL Database a Azure SQL Managed Instance pomocí dotazu na SERVERPROPERTY('EngineEdition'). Při běhu v prostředí Azure SQL backend při přechodných chybách opakuje pokusy o připojení (například při dočasných omezeních prostředků nebo krátkodobých výpadcích sítě).

Toto chování můžete upravit pomocí voleb connection_retries a connection_retry_backoff_time:

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

Tato nastavení platí jenom pro počáteční připojení. Back-end neopakuje neúspěšné dotazy. Pokud dotaz po vytvoření připojení selže s přechodnou chybou, výjimka se rozšíří do kódu aplikace. K zajištění odolnosti na úrovni dotazů použijte logiku opakování na úrovni aplikace (například django-retry-db nebo vlastní middleware).

Pomalé dotazy a regrese plánů

Tyto problémy obvykle potřebují analýzu na straně serveru spolu s kontrolou dotazů na úrovni Django.

Dotaz se zpomaluje nebo začne narážet na časový limit.

Příznaky:

Stejná sada dotazů se postupem času zpomaluje nebo po nasazení, změně indexu či aktualizaci statistik začne narážet na časový limit.

Možné příčiny a řešení:

• Začínáme s integrovanými sestavami výkonu

  Pro SQL Server a Azure SQL Managed Instance otevřete v aplikaci SQL Server Management Studio Řídicí panel výkonu. Pro Azure SQL Database otevřete Query Performance Insight pro Azure SQL Database. Tyto nástroje jsou obvykle lepším prvním krokem než ad hoc dotazy DMV, protože rychle zobrazují nákladné dotazy, čekání a tlak na prostředky.

• Regrese plánu

  Pomocí Query Store vyhledejte pomalý dotaz a zkontrolujte, jestli má více plánů. Začněte zobrazeními Dotazy se zhoršeným výkonem a Dotazy s nejvyšší spotřebou prostředků, která jsou popsána v osvědčených postupech pro monitorování úloh pomocí Query Store.

• Neefektivní plán provádění

  Otevřete skutečný plán provádění příkazu a zkontrolujte prohledávání tabulek nebo indexů, rozsáhlé vyhledávání klíčů, přelití hodnot hash nebo nepřesné odhady řádků. Základní informace najdete v tématu Přehled plánu provádění.

• Bylo identifikováno nesprávné úzké místo

  Pokud dotaz není vázán na procesor, použijte Query Store statistiky čekání a identifikujte kritické body k rozlišení procesoru, paměti, vstupně-výstupních operací disku, blokování a tlaku připojení.

• Oprava použitá v nesprávné vrstvě

  Použijte nejmenší efektivní opravu: přidejte nebo upravte indexy, aktualizujte statistiky, snižte vybrané sloupce a řádky nebo dávkové velké zápisy. Pokud potřebujete nouzové zmírnění dopadů, může správce DBA dočasně vynutit známý funkční plán v Query Store, zatímco odstraníte hlavní příčinu.

Použití dbshellu pro interaktivní dotazy

Příkaz pro správu Django dbshell otevře interaktivní prostředí SQL připojené k vaší databázi:

python manage.py dbshell

Backend používá sqlcmd, když nakonfigurujete ovladač Microsoft ODBC, nebo isql, když používáte FreeTDS. Ověřte, že je nástroj ve vaší cestě:

• Windows: sqlcmd je součástí nástrojů SQL Server nebo si ho můžete stáhnout samostatně.
• Linux a macOS: Nainstalujte mssql-tools18 z úložiště Microsoft.

Související obsah

• Referenční informace ke konfiguraci mssql-django
• Možnosti připojení pro mssql-django
• Logika opakování a odolnost připojení pomocí mssql-django
• Omezení a nepodporované funkce v mssql-django
• Řídicí panel výkonu
• Query Performance Insight pro službu Azure SQL Database
• Sledujte výkon pomocí nástroje Query Store
• Analýza skutečného plánu provádění
• Řešení potíží s wikiwebem
• Nejčastější dotazy