Django háttérrendszer SQL Server - mssql-django

mssql-django a Microsoft Django adatbázis-háttérrendszere az SQL Serverhez, az Azure SQL Database-hez, az Azure SQL Managed Instance-hez és a Microsoft Fabricben található SQL-adatbázishoz. A csatlakozáshoz állítsa a(z) ENGINE értékét "mssql" értékre a Django DATABASES konfigurációjában. A háttérrendszer a pyodbc-ra és a Microsoft ODBC-illesztőre épül a SQL Server számára, és támogatja a Django 3.2-től 6.0-ig, Python 3.8-3.14-ig, és SQL Server 2016-2025-ig.

Válassza ki a kiindulási pontot

Azure SQL üzemi alapkonfigurációja

Használja ezt a kódrészletet egy éles Azure SQL konfiguráció kiindulópontjaként. Négy fájlt egyesít: settings.py (a Django-adatbázis konfigurációja, köztes szoftverregisztráció és naplózás), myproject/retry.py (az átmeneti hibakatalógus és retry_on_transient a dekorátor), myproject/middleware.py (a kérelemszintű újrapróbálkozási köztes szoftver) és myapp/views.py (például tranzakciós nézet).

# settings.py

import logging.config
import os

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": os.environ["SQL_DATABASE"],          # for example, appdb
        "HOST": os.environ["SQL_SERVER"],            # for example, contoso.database.windows.net
        "PORT": "1433",
        "CONN_MAX_AGE": 300,                         # reuse pooled connections for 5 minutes
        "CONN_HEALTH_CHECKS": True,                  # validate connections before reuse (Django 4.1 and later)
        "ATOMIC_REQUESTS": False,                    # wrap mutating views in transactions explicitly (see the following view example)
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": (
                "Authentication=ActiveDirectoryMsi;"
                "Encrypt=yes;"
                "TrustServerCertificate=no;"
                # ODBC driver reconnects connections dropped while idle.
                "ConnectRetryCount=3;"
                "ConnectRetryInterval=10;"
            ),
            # Backend-level retry for the initial connect call. Complements
            # ConnectRetryCount, which only covers idle drops on an
            # already-established connection.
            # See Retry logic and connection resilience for the recognized error list.
            "connection_retries": 3,
            "connection_retry_backoff_time": 5,
        },
    },
}

MIDDLEWARE = [
    # Defined in myproject/middleware.py. Catches transient OperationalErrors
    # and retries the request. Add "1205" (deadlock victim) and "1222"
    # (lock-request timeout) to TRANSIENT_ERROR_CODES to also retry
    # statement-level failures.
    "myproject.middleware.DatabaseRetryMiddleware",
    "django.middleware.security.SecurityMiddleware",
    # ... your other middleware
]

LOGGING_CONFIG = None
logging.config.dictConfig({
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "json": {
            "format": (
                '{"time":"%(asctime)s","level":"%(levelname)s",'
                '"logger":"%(name)s","message":"%(message)s"}'
            ),
        },
    },
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
            "formatter": "json",
        },
    },
    "loggers": {
        "django.db.backends": {
            "handlers": ["console"],
            "level": "WARNING",      # raise to INFO or DEBUG to capture SQL
            "propagate": False,
        },
        "django.request": {
            "handlers": ["console"],
            "level": "WARNING",
            "propagate": False,
        },
        "mssql": {
            "handlers": ["console"],
            "level": "INFO",
            "propagate": False,
        },
    },
})

Adja meg a megosztott átmeneti hibakatalógust és a retry_on_transient dekoratőrt a következőben myproject/retry.py:

# myproject/retry.py
import functools
import logging
import random
import re
import time

from django.db import OperationalError, connection

logger = logging.getLogger(__name__)

TRANSIENT_ERROR_CODES = {
    "64", "233", "4221",
    "10053", "10054", "10928", "10929",
    "40197", "40501", "40613",
    "49918", "49919", "49920",
    # Add "4060" only if targeting Azure SQL with geo-replication failover.
    # Add "1205" (deadlock victim) and "1222" (lock-request timeout) to
    # also retry statement-level failures.
}

# Microsoft ODBC driver formats native error codes as "(<number>)" in the
# message. Parenthesized matches avoid false positives for short codes like "64".
_CODE_RE = re.compile(r"\((\d+)\)")


def is_transient(error):
    codes_in_message = set(_CODE_RE.findall(str(error)))
    return bool(codes_in_message & TRANSIENT_ERROR_CODES)


def retry_on_transient(max_retries=3, base_delay=1, max_delay=30):
    """Retry on transient database errors with exponential backoff and full jitter."""

    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(max_retries + 1):
                try:
                    return func(*args, **kwargs)
                except OperationalError as e:
                    if attempt < max_retries and is_transient(e):
                        capped = min(max_delay, base_delay * (2 ** attempt))
                        delay = random.uniform(0, capped)
                        logger.warning(
                            "Transient error in %s (attempt %d/%d), retrying in %.2fs: %s",
                            func.__name__, attempt + 1, max_retries, delay, e
                        )
                        connection.close()
                        time.sleep(delay)
                        continue
                    raise
        return wrapper
    return decorator

Definiálja a kérelemszintű köztes réteget itt: myproject/middleware.py. Újra felhasználja, is_transient hogy mindkét réteg felismerje ugyanazt a hibakódkészletet:

# myproject/middleware.py
import logging
import random
import time

from django.db import OperationalError, connection

from myproject.retry import is_transient

logger = logging.getLogger(__name__)


class DatabaseRetryMiddleware:
    """Retry the entire request on transient database errors."""

    def __init__(self, get_response):
        self.get_response = get_response
        self.max_retries = 3
        self.base_delay = 1   # seconds; doubled each attempt
        self.max_delay = 30   # cap on a single sleep, regardless of attempt

    def __call__(self, request):
        for attempt in range(self.max_retries + 1):
            try:
                return self.get_response(request)
            except OperationalError as e:
                if attempt < self.max_retries and is_transient(e):
                    capped = min(self.max_delay, self.base_delay * (2 ** attempt))
                    delay = random.uniform(0, capped)
                    logger.warning(
                        "Transient DB error (attempt %d/%d), retrying in %.2fs: %s",
                        attempt + 1, self.max_retries, delay, e
                    )
                    connection.close()
                    time.sleep(delay)
                    continue
                raise

Mivel a(z) ATOMIC_REQUESTSFalse, a módosító nézeteknek saját tranzakciót kell nyitniuk. Csomagolja be a atomic() blokkot úgy @retry_on_transient , hogy minden újrapróbálkozás egy friss tranzakciót futtasson:

# myapp/views.py
from django.db import transaction
from django.http import JsonResponse

from myproject.retry import retry_on_transient
from .models import Order


# Exponential backoff with full jitter: sleeps random within [0,2], [0,4], [0,8] seconds.
@retry_on_transient(max_retries=3, base_delay=2)
def submit_order(request, order_id):
    with transaction.atomic():
        order = Order.objects.select_for_update().get(id=order_id)
        order.status = "submitted"
        order.save()
    return JsonResponse({"id": order.id, "status": order.status})

Note

Ez az alapkonfiguráció két rétegben regisztrálja az újrapróbálkozási műveletet. A middleware biztosítékként szolgál az adatbázis-hozzáféréshez a dekorátorral ellátott nézeteken kívül, például az adminfelületen, a szignálokban vagy más middleware-ben. A @retry_on_transient dekoratőr finomabb vezérlést biztosít a nézetkészítőknek, hogy mely műveletek újrapróbálkoznak. Ha egy átmeneti hiba átjut a dekorátoron, a middleware újra lefuttatja a teljes kérést, így a legrosszabb esetben akár kilenc próbálkozásra is sor kerülhet, mielőtt a kliens hibát kap. Ha ez a felső határ túl magas a késleltetési keretéhez, hagyjon el egy réteget, vagy csökkentse a megtartott rétegen a max_retries értékét.

A konfiguráció egyes részeiről további információt a konfigurációs referencia, a kapcsolatbeállítások, a kapcsolatkészletezés, az újrapróbálkozási logika és a kapcsolat rugalmassága, valamint a Microsoft Entra hitelesítés című témakörben talál.

Legfontosabb funkciók

  • Beépülő Django-háttérrendszer: Állítsa a(z) ENGINE értékét "mssql" értékre, és a Django ORM-je, migrációi, adminfelülete és felügyeleti parancsai az SQL Serverrel működnek.
  • Pyodbc és ODBC Driver 18: TLS-titkosított kapcsolatok alapértelmezés szerint és széles körű platformtámogatás Windows, Linux és macOS rendszeren.
  • Széles verziómátrix: Django 3.2–6.0, Python 3.8–3.14, és SQL Server 2016 és 2025 között.
  • Microsoft Entra ID hitelesítés: Jelszó nélküli kapcsolatok felügyelt identitással, szolgáltatásnévvel, interaktív és integrált folyamatokkalextra_params.
  • Django-migrálások: Sémamigrálások SQL Server, beleértve SQL Server-specifikus oszloptípusokat is.
  • JSONField-támogatás: Natív JSONField támogatás az nvarchar(max) tárolásra és a Django kereséseire épülve.
  • Always Encrypted: Bizalmas oszlopok ügyféloldali titkosítása.
  • Tömeges műveletek: bulk_create és bulk_update SQL Serveren, megfelelő kötegméretekkel.
  • Átmeneti újrapróbálkozások: Beépített kezelés a gyakori Azure SQL átmeneti hibákhoz a kapcsolat és a lekérdezés végrehajtása során.
  • inspectdb: Django-modellek létrehozása meglévő SQL Server sémákból.

Első lépések

Cikk Description
Installation Telepítse a(z) mssql-django és a Microsoft ODBC-illesztőprogramot a SQL Serverhez.
Rövid útmutató: Django csatlakoztatása SQL Server Kapcsolja össze a Django-projektet az SQL Serverrel, majd futtassa az első migrációját.

Konfigurálás és csatlakoztatás

Cikk Description
Konfigurációs referencia A Django DATABASES szótár teljes referenciája mssql-django használatával.
Kapcsolati beállítások OPTIONS, extra_params, időtúllépések és az ODBC-illesztőprogram konfigurálása.
Kapcsolatkészletezés CONN_MAX_AGE, CONN_HEALTH_CHECKS és külső pool integrációja.
Újrapróbálkozási logika és kapcsolati rugalmasság Átmeneti hibák észlelése, kapcsolatok és lekérdezések újrapróbálkozása.
Microsoft Entra-hitelesítés Jelszó nélküli hitelesítés felügyelt identitással, szolgáltatásnévvel, interaktív és integrált folyamatokkal.
biztonsági ajánlott eljárások Paraméterezés, titkos kódok kezelése, minimális jogosultság és titkosítás.
Mindig titkosítva Ügyféloldali titkosítás konfigurálása bizalmas oszlopokhoz.

Modellek, migrálások és adattípusok

Cikk Description
Adatbázis-migrálások Django-migrációkat futtathat SQL Serveren, beleértve az SQL Server-specifikus oszloptípusokat is.
A Django-mezők SQL Server-típusmegfeleltetései A Django-modell mezőinek leképezése SQL Server adattípusokra.
JSONField-támogatás Használja JSONField SQL Server és Django keresésekhez.
Visszafejtett mérnökmodellek az inspectdb használatával Django-modellek létrehozása meglévő SQL Server sémákból.
Időzóna támogatása USE_TZ, datetimeoffset és időzóna-tudatos dátum-idő értékek.

Adatok lekérdezése és használata

Cikk Description
Tömeges műveletek bulk_create, bulk_updateés a köteg méretének finomhangolása.
Tranzakciókezelés atomic, elkülönítési szintek, mentési pontok és holtpont kezelése.
Nyers SQL-lekérdezések RawSQL, connection.cursor() és SQL Server-specifikus szintaxis.
Tárolt eljárások SQL Server tárolt eljárások hívása Djangóból.

Üzembe helyezés, tesztelés és hangolás

Cikk Description
Az Azure App Service üzembe helyezése Django-webhely üzembe helyezése az Azure App Service-be az mssql-django használatával.
Konténeres és helyi fejlesztés Docker-tárolók, devcontainers és CI-folyamatok a Django + SQL Server számára.
Testing Futtassa a Django tesztcsomagokat SQL Serveren.
Teljesítmény finomhangolása Indexek, lekérdezési minták, kapcsolat újrafelhasználása és kötegméretek.
Troubleshooting Gyakori hibák, ODBC-diagnosztika és naplózás.

Migrálás az mssql-django-ba

Cikk Description
Migrálás a django-mssql-backendről Váltás a közösségi django-mssql-backend csomagról a mssql-django csomagra.
Migrálás más adatbázisokból Django-projekt áthelyezése egy másik adatbázis háttérrendszeréből SQL Server.
Migrálás a PostgreSQL-ből Átfogó útmutató Django-fejlesztőknek a PostgreSQL-ről SQL Serverre való áttéréshez.
Cikk Description
Támogatási életciklus Támogatott Django, Python és SQL Server verziók.
Újdonságok Verzióelőzmények és kiadási kiemelések.
Az mssql-django korlátozásai és nem támogatott funkciói Háttérbeli korlátozások és nem támogatott funkciók.
FAQ Gyakori kérdések.

Kapcsolódó tartalom

  • Last updated on