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.

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ü bulunamadı

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

  SQL Server için Microsoft ODBC Sürücüsünü yükleyin. İndirme bağlantıları için bkz. SQL Server için ODBC Sürücüsünü İndirme.

• 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": "<your-database>",
          "USER": "<your-username>",
          "PASSWORD": "<your-password>",
          "HOST": "<your-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.

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

Olası nedenler ve çözümler:

• Yanlış kimlik bilgileri

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

• 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.

• 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.

Tarih ve saat sorunları

USE_TZ=True olduğunda Now() 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: 1.7.2 veya sonraki bir sürüme mssql-django yükseltin. Sürüm 1.7.2, saat dilimine duyarlı Now() SQL oluşturma ve datetimeoffset uzaklık işlemeyi düzeltir.

AttributeError ararken .explain()

Belirtiler:

AttributeError: ... explain_format ...

Çözüm: 1.7.2 veya sonraki bir sürüme mssql-django yükseltin. Sürüm 1.7.2, Django 4.0 ve üzeri için derleyici uyumluluğunu düzeltir ve meta verileri açıklar.

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 karakter verilerini SQL Server yanlış yorumladığında pyodbc oluşur.

Unicode kodlama hataları

Belirtiler:

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

Çözüm: Sözlükte kodlamayı pyodbc yapılandırınOPTIONS:

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

FreeTDS sorunları

FreeTDS, Microsoft ODBC sürücüsünden farklı belirli bir 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ı

Kapsayıcı görüntüleri için açık ODBC sürücüsü yüklemesi ve derleme bağımlılıkları gerekir.

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

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 \
    && apt-get purge -y --auto-remove 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