mssql-django sorunlarını giderme

SQL Server, Azure SQL Veritabanı, Azure SQL Yönetilen Örneği ve Microsoft Fabric'teki SQL veritabanı için mssql-django arka ucundaki yaygın sorunları tanılayın ve çözün.

mssql-django 2.0, varsayılan pyodbc sürücü yolunu ve isteğe bağlı bir mssql-python sürücü yolunu destekler. Daha fazla bilgi için, mssql-django için veritabanı sürücüsünü seç sayfasına bakınız.

Bağlantı sorunları

Bu bölüm, en yaygın bağlantı hatalarını ve bunların nasıl çözüleceğini kapsar.

ODBC sürücüsü pyodbc yolunda bulunmadı

Belirtiler:

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

Olası nedenler ve çözümler:

• ODBC sürücüsü yüklü değil

  Microsoft ODBC Sürücüsünü SQL Server için varsayılan pyodbc yolunu kullandığınızda yükleyin. İndirme bağlantıları için bkz. SQL Server için ODBC Sürücüsünü İndirme. mssql-python yolu, harici olarak yüklenmiş bir ODBC sürücüsü kullanmaz.

• Birden çok sürücü sürümü yüklü

  Tam sürücü adını veya yolunu settings.py içinde belirtin:

  DATABASES = {
      "default": {
          "ENGINE": "mssql",
          "NAME": "<database>",
          "USER": "<user_id>",
          "PASSWORD": "<password>",
          "HOST": "<server>",
          "PORT": "1433",
          "OPTIONS": {
              "driver": "ODBC Driver 17 for SQL Server",
          },
      },
  }
  

  Linux'ta tam yolu belirtin:

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

• Yüklü sürücüleri denetleme

  • Linux/macOS'ta komutunu çalıştırın odbcinst -q -d.
  • Windows'da, Yönetim Araçları'ndaODBC Veri Kaynakları'nı denetleyin.

MSSQL-python bağlantı seçeneğini reddediyor

Belirtiler:

"python_driver": "mssql_python" ayarlayan bir diğer ad, pyodbc bağlantı dizesi anahtar sözcüklerini OPTIONS["extra_params"] içine taşıdıktan sonra bağlantı kurulumu sırasında şu hatalardan biriyle başarısız olur:

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

Mesajdaki anahtar kelime adı küçük harfe dönüştürüldüğünden, LongAsMax olarak yazdığınız bir anahtar kelime longasmax olarak görünür. ConnectionStringParseError DB-API istisna hiyerarşisinin bir parçası olmadığı için Django bunu django.db.utils hata olarak yeniden sarmıyor.

Olası nedenler ve çözümler:

• extra_params içindeki yalnızca pyodbc’ye özgü anahtar sözcük

  mssql-python akışı, extra_params öğesini izin verilenler listesine göre doğrular. DRIVER ve APP sürücüye ayrılır ve formu Reserved keyword üretir. DSN, SERVERNAME, LongAsMax ve yalnızca pyodbc'ye özgü ColumnEncryption, WSID, AnsiNPW, Current Language, Network Library, UseFMTONLY, Regional, Description, QuotedId, Connect Timeout ve Unknown keyword gibi anahtar sözcükler izin listesinde değildir ve MARS_Connection formunu oluşturur. Anahtar kelimeyi kaldırın veya o ODBC seçeneğine ihtiyaç duyan bir takma ad için varsayılan pyodbc yolunu kullanın.

• mssql-python'u kontrol etmesi beklenen sürücü seçeneği

  mssql-python yolu driver, dsn, host_is_server ve unicode_results öğelerini yok sayar. HOST ve PORT, SERVER=<server>,<port> haline gelir ve boş bir HOST, localhost haline gelir.

MSSQL-python bağımlılığı çok eski

Belirtiler:

"python_driver": "mssql_python" değerini ayarlayan bir takma ad, bağlantı kurulumu sırasında şu hatalardan biriyle başarısız olur:

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

İkinci biçim, mssql_python modülünün hiçbir şekilde içe aktarılamadığı anlamına gelir.

Çözüm: Kurulum mssql-python>=1.15.0. mssql-django 2.0, mssql-python>=1.15.0 bildirir; bu nedenle normal bir pip install mssql-django, desteklenen platformlarda uyumlu bir sürüme çözümlenir.

Driver 17 yedek sistemi mssql-python için geçerli değil

Belirtiler:

"python_driver": "mssql_python" ayarlayan bir takma ad, Microsoft ODBC Driver 17 for SQL Server yüklü olmasına rağmen yine de başarısız olur.

Bu dava için ayırt edici bir hata yok. mssql-python kod yolu, driver seçeneğini sessizce yok sayar; bu nedenle bağlantı, altta yatan hangi hata geçerliyse onunla başarısız olur. Sürücü adını bunun yerine extra_params içine taşıdıysanız Reserved keyword 'driver' hatası alırsınız. mssql-python bağlantı seçeneğini reddediyor.

Çözüm: Takma adın harici olarak yüklenmiş bir ODBC Sürücüsü 17 kullanması gerekiyorsa, varsayılan pyodbc yolunu kullanın. mssql-python kod yolu Driver 17'ye geri düşmez ve driver seçeneğini göz ardı eder. O yol için ayrı ayrı bir ODBC sürücüsü gerekmez.

Bağlantı reddedildi

Belirtiler:

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

Olası nedenler ve çözümler:

• TCP/IP SQL Server etkin değil

  • SQL Server Yapılandırma Yöneticisi'i açın.
  • SQL Server Ağ Yapılandırması altında TCP/IP'yi etkinleştirin.
  • TCP/IP Özellikleri'nde, bağlantı için kullanılan IP adresini etkinleştirin.
  • SQL Server hizmetini yeniden başlatın.

• Güvenlik duvarı 1433 numaralı bağlantı noktasını engelliyor

  • Güvenlik duvarı kurallarının 1433 numaralı bağlantı noktasında gelen bağlantılara izin verdiğini doğrulayın.
  • Azure SQL için Azure portalı güvenlik duvarı ayarlarına istemci IP'nizi ekleyin.

• Yanlış sunucu adı veya bağlantı noktası

  Yapılandırmanızdaki HOST ve PORT değerlerini doğrulayın.

Oturum açılamadı

Belirtiler:

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

mssql-python yolu üzerinde:

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

Olası nedenler ve çözümler:

• Yanlış kimlik bilgileri

  Kullanıcı adını ve parolayı doğrulayın.

• NAME içindeki veritabanı mevcut değil

  SQL Server'da mssql-python yolu, hatalı bir parolada olduğu gibi aynı iletiyle aynı OperationalError hatasını üretir; bu nedenle yalnızca ileti, bunlardan hangisiyle karşılaştığınızı söylemez. Kimlik bilgilerini değiştirmeden önce veritabanının var olduğunu doğrulayın. Girişi tek başına test etmek için NAME öğesini master öğesine yönlendirin: eğer bağlantı kurulursa, kimlik bilgileri doğrudur ve sorun veritabanındadır. pyodbc yolu bu durumu ayrı ayrı olarak bildirir.Cannot open database "<database>" requested by the login. The login failed. (4060)

  Azure SQL Veritabanı bu durumu farklı şekilde bildiriyor. mssql-python yolu Driver Error: General error; DDBC Error: [Microsoft][SQL Server]Cannot open server "<server>" requested by the login. The login failed. hatasını üretir. İletide sunucunun adı geçiyor, ancak sunucu adı doğru. Bunun yerine kontrol edin NAME .

• Kullanıcı yok

  Oturum açma bilgilerinin hedef veritabanındaki bir kullanıcıyla eşlendiğini onaylayın.

• SQL Server kimlik doğrulaması devre dışı bırakıldı

  Karma mod kimlik doğrulamasını etkinleştirin veya Windows veya Microsoft Entra kimlik doğrulamasını kullanın.

Bağlantı zaman aşımına uğradı

Belirtiler:

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

Olası nedenler ve çözümler:

• Ağ gecikme süresi

  OPTIONS'ta connection_timeout değerini artırın.

• Otomatik duraklatma etkin Azure SQL Veritabanı sunucusuz

  Otomatik olarak duraklatılan bir veritabanı, ilk bağlantı denemesinde yeniden başlatılır ve veritabanı yeniden başlatılırken bu deneme 40613 hatasıyla başarısız olabilir. connection_timeout En az 60'a ayarlayın ve ilk bağlantıyı tekrar deneyin. Daha fazla bilgi için Azure SQL Veritabanı serverless ve Auto-pause and auto-resume bölümlerine bakınız.

• Aşırı yüklenmiş sunucu

  connection_retries ve connection_retry_backoff_time öğelerini artırın.

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

Geçiş sorunları

Bu hatalar, SQL Server karşı Django geçiş işlemleri sırasında oluşur.

Ham SQL ve GROUP BY sorunları

Bu hatalar, GROUP BY yan tümcesi içeren ham veya açıklamalı sorguların arka uçtaki yer tutucu yeniden yazma adımından geçmesiyle ortaya çıkar.

IndexError GROUP BY üzerinde kaçışlı %% ve gerçek parametrelerle

Belirtiler:

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

Sorgu, GROUP BY ifadesi olmadan da çalışır ve kaçışlı %% değişmezi olmadan da çalışır; ancak her ikisi de gerçek bir %s parametresiyle birlikte bulunduğunda çalışmaz.

Çözüm: Güncel mssql-django sürüme yükseltmek. Arka uç, yer tutucu yeniden yazma regex’ini yalnızca %s ve %% ile sınırlar; böylece escape edilmiş %% sabitleri aynen korunur ve sahte yer tutucular eklenmez.

NotImplementedError için IntegerChoices ham GROUP BY sorgularında

Belirtiler:

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

Aynı enum değeri, ORM sorgularında ve , olmayan GROUP BYham sorgularda çalışır, ancak bir GROUP BY madde içeren ham sorguya parametre olarak geçirildiğinde başarısız olur.

Çözüm: Güncel mssql-django sürüme yükseltmek. Arka uç, isinstance yolunda parametre türü denetimleri için GROUP BY kullanır; bu nedenle IntegerChoices (bir int alt sınıfı) doğru şekilde bağlanır. bool hala biti bağlıyor ve sade int değişmiyor.

Regex arama sorunları

__regex veya __iregex satır döndürmez

Belirtiler: Sorgu hatasız çalışır ve satırlar desenle eşleşse bile boş bir sonuç kümesi döndürür.

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

Sebep: dbo.REGEXP_LIKE desendeki kelimenin tam anlamıyla boşluk eksikliğini görmezden gelir. Örüntü, sanki ^Widget\d+$ imiş gibi eşleştirilir; bu koşulu boşluk içeren hiçbir değer sağlayamaz. Hiçbir şey yükselmiyor, bu yüzden boş sonuç veri sorunu gibi görünüyor.

Çözüm: Boşluğu bir kaçış dizisi veya karakter sınıfı olarak yazın:

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

Cannot find ... dbo.REGEXP_LIKE

Belirtiler:

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

mssql-python yolunda:

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.

Sebep: CLR assembly sorguladığınız veritabanına yüklenmemiş. Veritabanına göre kurulu, sunucuya göre değil.

Çözüm: python manage.py install_regex_clr <database> öğesini o veritabanına karşı çalıştırın. Veritabanını silip yeniden oluşturduktan sonra tekrar çalıştırın. Bkz. Regex aramalarını ayarlama.

Tarih ve saat sorunları

Now() olduğunda USE_TZ=True değerler kaydırılır

Belirtiler:

Django Now(), auto_now veya auto_now_add ile yazılan zaman damgaları, SQL Server ana bilgisayarının saat dilimi UTC değilse kaydırılır.

Çözüm: Güncel mssql-django sürüme yükseltmek. Arka uç, zaman dilimine duyarlı Now() SQL üretir, datetimeoffset ofsetlerini korur ve zaman dilimi verilerini zoneinfo ve tzdata aracılığıyla okur.

AttributeError ararken .explain()

Belirtiler:

AttributeError: ... explain_format ...

Çözüm: Güncel mssql-django sürüme yükseltmek. Arka uç, desteklenen her Django sürümü için explain meta verilerini işler.

AutoField değiştirilemez

Belirtiler:

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

Çözüm: SQL Server, bir alanı AutoField türünden veya AutoField türüne değiştirmeyi desteklemez. İstenen alan türüne sahip yeni bir model oluşturun, verileri el ile geçirin ve eski tabloyu bırakın. Geçici çözümler için bkz. mssql-django ile veritabanı geçişleri.

Yabancı anahtar kısıtlamasıyla yeniden adlandırma başarısız oluyor

Belirtiler:

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

Çözüm: SQL Server sütunları yeniden adlandırmadan önce yabancı anahtar kısıtlamalarının bırakılması gerekir. Geçişinizde SeparateDatabaseAndState kullanın. Örnek için bkz. mssql-django ile veritabanı geçişleri.

Kodlama sorunları

Kodlama hataları genellikle pyodbc yolunda, pyodbc SQL Server'dan gelen karakter verisi yanlış yorumlandığında meydana gelir.

Unicode kodlama hataları

Belirtiler:

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

Çözüm: Sözlükte kodlamayı OPTIONS yapılandırmakpyodbc. mssql-python yolu, unicode_results öğesini yok sayar.

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

FreeTDS sorunları

FreeTDS, Microsoft ODBC sürücüsünden farklı pyodbc'ye özgü yapılandırma gerektirir.

host_is_server hatası

Belirtiler:

FreeTDS'yi belirtmeden host_is_serverkullanırken bağlantı başarısız oluyor.

Çözüm: FreeTDS kullanırken host_is_server öğesini True olarak ayarlayın:

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

FreeTDS yapılandırması hakkında daha fazla bilgi için bkz. mssql-django için bağlantı seçenekleri.

Veritabanı sorunlarını test edin

Test veritabanı oluşturma ve yok etme işlemi, kimlik doğrulama yönteminize bağlı olarak başarısız olabilir.

Yönetilen kimlikle test veritabanı oluşturulamıyor

Belirtiler:

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

Or:

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

ActiveDirectoryMsi (yönetilen kimlik) kimlik doğrulamasını kullandığınızda test çalıştırıcısı test veritabanını oluşturamaz veya yok edemez. Bu sınırlamanın mevcut nedeni:

• Yönetilen kimlik kimlik bilgileri konak ortamından (Azure VM ve App Service gibi) alınır.

• Test yürütücüsü, teardown aşamasında test veritabanının kimlik bilgileriyle bağlanmayı dener.

• Yönetilen kimliğe veritabanı düzeyinde roller verilebilir, ancak test veritabanı oluşturma ve silme işlemleri genellikle test çalıştırıcılarının genellikle sahip olmadığı sunucu düzeyinde izinler gerektirir.

Etkilenen kimlik doğrulama yöntemleri:

• ActiveDirectoryMsi (Azure yönetilen kimliği)
• ActiveDirectoryServicePrincipal (yalnızca sunucu düzeyinde yapılandırıldığında)

Desteklenen kimlik doğrulama yöntemleri (test veritabanı oluşturma işlemi çalışır):

• ActiveDirectoryPassword
• ActiveDirectoryIntegrated
• SQL kimlik doğrulaması (kullanıcı adı/parola)

Test ortamları için kimlik doğrulama ödünleşimleri

Method	Gizsiz	Otomatik test DB oluşturma/bırakma ile çalışır	Tipik kullanım
ActiveDirectoryMsi	Yes	Genellikle hayır (sunucu düzeyinde haklar verilmediği sürece)	Azure barındırılan üretim iş yükleri
ActiveDirectoryServicePrincipal	Hayır (istemci gizli anahtarı/sertifika)	Verilen sunucu düzeyindeki haklara bağlıdır	Açıkça tanımlanmış kimlik yönetimi ile CI/CD
ActiveDirectoryPassword	Hayı	Evet (yeterli SQL izinleriyle)	Geliştirici ve denetimli CI ortamları
SQL kimlik doğrulaması	Hayı	Evet (yeterli SQL izinleriyle)	Yerel veya yalıtılmış test ortamları

Çözümler:

• Geliştirme için: Test veritabanının kaldırılmasını atlamak için --keepdb bayrağını kullanın:

  python manage.py test --keepdb
  

• CI/CD iş hatları için: Özel bir test veritabanını önceden oluşturun ve yönetilen kimliğe CREATE TABLE ve ALTER izinlerini verin:

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

• Alternatif: Test ortamları için SQL kimlik doğrulamasını kullanın veya CI/CD test çalıştırıcıları için ActiveDirectoryPassword öğesine geçin.

Geri alma prosedürleri

Geçiş işlemi yarıda başarısız olduğunda, bilinen iyi duruma dönmek için bu geri alma dizisini kullanın:

1. Ek şema kaymasını önlemek için uygulama yazmalarını durdurun.

2. Geçiş durumunu inceleyin:

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

3. Sorunsuz olduğu bilinen son geçişe geri dönün:

   python manage.py migrate <app_label> <previous_migration>
   

4. Şema ve geçiş geçmişi birbirinden ayrılırsa, durumu ancak gerçek veritabanı şemasını doğruladıktan sonra dikkatli bir şekilde --fake onarın.

5. Önce bir hazırlama ortamında geçişleri yeniden çalıştırın, ardından üretimi yeniden deneyin.

Important

Bırakma, yeniden adlandırma ve sütun türü değişiklikleri gibi yıkıcı geçişler için dağıtımdan önce test edilmiş bir yedekleme alın. Migrasyonla geri alma mümkün değilse, yedekten geri yükleyin ve doğrulanmış geçişleri yeniden uygulayın.

Docker ve konteyner sorunları

Konteyner görüntüleri, varsayılan pyodbc yolunu kullandığınızda açık ODBC sürücü kurulumu ve derleme bağımlılıkları gerektirir. mssql-python yolunda ayrı bir ODBC sürücü kurulumu yoktur, ancak yine de unixODBC çalışma zamanına ihtiyaç duyar, çünkü arka uç Django yüklerken pyodbc'yi içe aktarır.

KAPSAYıCıda ODBC sürücüsü bulunamadı

Belirtiler:

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

Olası nedenler ve çözümler:

• Kapsayıcı görüntüsünde ODBC sürücüsü yüklü değil

  Slim veya Alpine temel imajları ODBC sürücüsünü içermez. pyodbc kullanıyorsanız Dockerfile'ınıza Microsoft APT deposunu ekleyin ve msodbcsql18 öğesini yükleyin. Dockerfile’ın tam bir örneği için bkz. App Service’e dağıtma.

• Eksik unixodbc-dev paket

  pyodbc tekerleği, libodbc.so ile bağlantılıdır. Python paketleri yüklemeden önce (Debian/Ubuntu) veya unixodbc-dev (RHEL/Fedora) yükleyin unixODBC-devel .

• apt-get autoremoveSürücü kurulumundan sonra söküldü libgssapi-krb5-2

  msodbcsql18, libgssapi-krb5-2 öğesini bağımlılık olarak bildirmeden çalışma zamanında yükler. Kütüphane genellikle curl bağımlılığı olarak gelir; bu nedenle curl ile --auto-remove paketini temizlemek veya ardından apt-get autoremove komutunu çalıştırmak onu kaldırır. İmaj sorunsuz oluşturuluyor, ancak ardından tüm bağlantılar başarısız oluyor. libgssapi-krb5-2 ögesini açıkça yükleyin ve sürücü kurulumundan sonra otomatik kaldırma yapmayın.

Sürüm 18'i yüklediğinizde sürücü 17 kayıp olarak bildirildi

Belirtiler:

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

Hata 17. sürümü adlandırıyor, ancak odbcinst -q -d 18. sürüm kayıtlı ve dpkg -l msodbcsql18 kurulu olduğunu gösteriyor.

Sebep: Sürüm 18 kayıtlı ama yüklenemiyor, bu yüzden mssql-django tekrar 17 sürümüne geri dönüyor ve o da yüklenmemiş. Yedek program, ikinci olarak denediği sürücüyü bildiriyor, arızalanan sürücüyü değil.

Çözüm: Kurulum libgssapi-krb5-2 ve yeniden inşa etmek. Kütüphanenin nasıl kaybolduğunu öğrenmek için önceki otomatik kaldırma notuna bakın.

Bir konteynere pyodbc modülü yükleme hatası

Belirtiler:

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

Sebep: Görselin unixODBC çalışma süresi yok. mssql-django, Django backend’i yüklediğinde pyodbc’yi import eder; bu yüzden bu hata, herhangi bir bağlantı kurulmaya çalışılmadan önce mssql-python tarafında da ortaya çıkar.

Çözüm: Kurulum unixodbc (veya unixodbc-dev).

MSSQL-Python sürücüsü yüklenemez

Belirtiler:

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

Sebep: Birlikte mssql-python gelen sürücü, Slim Base Images'te olmayan Kerberos çalışma zamanı kütüphanelerine ihtiyaç duyuyor.

Çözüm: Kurulum libkrb5-3 ve libgssapi-krb5-2.

pyodbc, ince görüntüler üzerinde derlenemiyor

Belirtiler:

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

Or:

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

Çözüm: derleme bağımlılıklarını önce pip installyükleyin:

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

Alternatif olarak, son görüntüyü küçük tutmak için çok aşamalı bir derleme kullanın:

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

Kapsayıcı SQL Server bağlanamıyor

Belirtiler:

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

Olası nedenler ve çözümler:

• Docker Compose hizmet adı konak olarak kullanılmaz

  Docker Compose kullanırken, DB_HOST değerini hizmet adına (örneğin, db) ayarlayın; localhost veya 127.0.0.1 olarak değil.

• SQL Server kapsayıcı hazır değil

  SQL Server kapsayıcısının başlatılması birkaç saniye sürer. Durum denetimi veya başlatma gecikmesi ekleyin:

  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
  

• Bağlantı noktası eşleme çakışmaları

  Konakta başka bir SQL Server örneği çalışıyorsa, kullanıma sunulan bağlantı noktasını (örneğin, 1434:1433) değiştirin ve Django yapılandırmanızı uygun şekilde güncelleştirin.

Azure SQL geçici hata kurtarma

mssql-django arka uç, SERVERPROPERTY('EngineEdition') sorgulayarak Azure SQL Veritabanı ve Azure SQL Yönetilen Örneği bağlantılarını otomatik olarak algılar. Azure SQL ile çalışırken arka uç, geçici hatalarda (örneğin geçici kaynak sınırları veya kısa süreli ağ kesintileri durumunda) bağlantıları yeniden dener.

Bu davranışı connection_retries ve connection_retry_backoff_time SEÇENEKLERİ ile ayarlayabilirsiniz:

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

Bu ayarlar yalnızca ilk bağlantı kurulumu için geçerlidir. Arka uç başarısız sorguları yeniden denemez. Bağlantı kurulduktan sonra bir sorgu geçici bir hatayla başarısız olursa, özel durum uygulama kodunuz için yayılır. Sorgu düzeyinde dayanıklılık için uygulama düzeyi yeniden deneme mantığını (örneğin, django-retry-db veya özel ara yazılım) kullanın.

Yavaş sorgular ve plan regresyonları

Bu sorunlar genellikle Django düzeyi sorgu incelemesiyle birlikte sunucu tarafı analizine ihtiyaç duyar.

Sorgu yavaşlar veya zaman aşımına uğrar

Belirtiler:

Aynı sorgu kümesi zamanla yavaşlar veya dağıtım, dizin değişikliği veya istatistik güncelleştirmesi sonrasında zaman aşımına başlar.

Olası nedenler ve çözümler:

• Yerleşik performans raporlarıyla başlayın

  SQL Server ve Azure SQL Yönetilen Örneği için SQL Server Management Studio'da Performans Panosu'nu açın. Azure SQL Veritabanı için Azure SQL Veritabanı için Sorgu Performansı İçgörüleri'ne tıklayın. Pahalı sorguları, beklemeleri ve kaynak baskısını hızla ortaya çıkardıkları için bu araçlar genellikle geçici DMV sorgularından daha iyi bir ilk adımdır.

• Regresyonu planlama

  Yavaş sorguyu bulmak ve birden çok planı olup olmadığını denetlemek için Query Store kullanın. Query Store ile iş yüklerini izlemek için en iyi yöntemler bölümünde açıklanan Regresyona Sahip Sorgular ve En Çok Kaynak Tüketen Sorgular görünümleriyle başlayın.

• Verimsiz yürütme planı

  İfadenin gerçek yürütme planını açın ve tablo veya dizin taramaları, büyük anahtar aramaları, hash spill’leri ya da hatalı satır tahminleri açısından kontrol edin. Arka plan için bkz . Yürütme planına genel bakış.

• Yanlış darboğaz tespit edildi

  Sorgu CPU'ya bağlı değilse Query Store bekleme istatistiklerini kullanın ve CPU, bellek, disk G/Ç, engelleme ve bağlantı baskısını ayırt etmek için performans sorunlarını belirleyin.

• Yanlış katmana uygulanan düzeltme

  En küçük etkili düzeltmeyi uygulayın: dizinleri ekleyin veya ayarlayın, istatistikleri güncelleştirin, seçili sütunları ve satırları azaltın veya büyük yazmaları toplu işleyin. Acil bir müdahale gerekirse, siz kök nedeni düzeltirken bir DBA Query Store’da bilinen, düzgün çalışan bir planın kullanılmasını geçici olarak zorlayabilir.

Etkileşimli sorgular için dbshell kullanma

Django'nun dbshell yönetim komutu veritabanınıza bağlı etkileşimli bir SQL kabuğu açar:

python manage.py dbshell

Arka uç, Microsoft ODBC sürücüsünü yapılandırdığınızda sqlcmd veya FreeTDS kullandığınızda isql kullanır. Aracın PATH'inizde olduğunu doğrulayın:

• Windows: sqlcmd SQL Server araçlarına dahildir veya ayrı olarak indirebilirsiniz.
• Linux ve macOS: Microsoft deposundan yükleyinmssql-tools18.

İlgili içerik

• mssql-django yapılandırma başvurusu
• mssql-django için bağlantı seçenekleri
• mssql-django ile mantığı ve bağlantı dayanıklılığını yeniden deneyin
• mssql-django'daki sınırlamalar ve desteklenmeyen özellikler
• Performans Panosu
• Azure SQL Veritabanı için Sorgu Performansı İçgörüleri
• Query Store'u kullanarak performansı izleyin
• Gerçek yürütme planını analiz etme
• Wiki sorunlarını giderme
• SSS