Memecahkan masalah mssql-django

Mendiagnosis dan mengatasi masalah umum pada backend mssql-django untuk SQL Server, Azure SQL Database, Azure SQL Managed Instance, dan database SQL di Microsoft Fabric.

mssql-django 2.0 mendukung jalur driver pyodbc bawaan dan jalur driver mssql-python opsional. Untuk informasi lebih lanjut, lihat Pilih driver database untuk mssql-django.

Masalah koneksi

Bagian ini mencakup kesalahan koneksi yang paling umum dan cara mengatasinya.

Driver ODBC tidak ditemukan di jalur pyodbc

Gejala:

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

Kemungkinan penyebab dan solusi:

Driver ODBC tidak terinstal

Instal Microsoft ODBC Driver untuk SQL Server saat Anda menggunakan jalur pyodbc default. Untuk tautan unduhan, lihat Mengunduh Driver ODBC untuk SQL Server. Jalur mssql-python tidak menggunakan driver ODBC yang terpasang secara eksternal.

Beberapa versi driver terinstal

Tentukan nama atau jalur driver yang tepat di 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",
        },
    },
}

Di Linux, tentukan jalur lengkap:

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

Periksa driver yang terinstal
- Di Linux/macOS, jalankan odbcinst -q -d.
- Pada Windows, periksa Sumber Data ODBC di Alat Administratif.

mssql-python menolak opsi koneksi

Gejala:

Alias yang menetapkan "python_driver": "mssql_python" gagal saat menyiapkan koneksi setelah Anda memindahkan kata kunci string koneksi pyodbc ke OPTIONS["extra_params"], dan menampilkan salah satu kesalahan berikut:

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

Nama kata kunci dalam pesan ditulis dengan huruf kecil, jadi kata kunci yang Anda tulis sebagai LongAsMax akan muncul sebagai longasmax. ConnectionStringParseError bukan bagian dari hierarki pengecualian DB-API, jadi Django tidak menggantinya sebagai django.db.utils error.

Kemungkinan penyebab dan solusi:

kata kunci khusus pyodbc di extra_params

Path mssql-python memvalidasi extra_params terhadap daftar yang diizinkan. DRIVER dan APP disediakan untuk pengemudi serta menghasilkan Reserved keyword formulir. DSN, SERVERNAME, MARS_Connection, dan kata kunci yang hanya digunakan oleh pyodbc seperti LongAsMax, ColumnEncryption, WSID, AnsiNPW, Current Language, Regional, QuotedId, Network Library, Description, UseFMTONLY, dan Connect Timeout tidak ada dalam daftar yang diizinkan dan menghasilkan bentuk Unknown keyword. Hapus kata kunci, atau gunakan path pyodbc default untuk alias yang membutuhkan opsi ODBC tersebut.
Opsi driver diperkirakan mengendalikan mssql-python

Jalur mssql-python mengabaikan driver, dsn, host_is_server, dan unicode_results. HOST dan PORT menjadi SERVER=<server>,<port>, dan HOST kosong menjadi localhost.

dependensi mssql-python terlalu usang

Gejala:

Alias yang mengatur "python_driver": "mssql_python" gagal saat pengaturan koneksi dengan salah satu kesalahan berikut:

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

Formulir kedua berarti mssql_python modul tersebut sama sekali tidak bisa diimpor sama sekali.

Solusi: Instal mssql-python>=1.15.0. mssql-django 2.0 mendeklarasikan mssql-python>=1.15.0, sehingga pip install mssql-django normal akan menentukan versi yang kompatibel di platform yang didukung.

Mekanisme fallback Driver 17 tidak diterapkan pada mssql-python

Gejala:

Alias yang ditetapkan "python_driver": "mssql_python" tetap gagal meskipun Microsoft ODBC Driver 17 untuk SQL Server sudah terpasang.

Tidak ada kesalahan mencolok untuk kasus ini. Mekanisme mssql-python mengabaikan opsi driver tanpa peringatan, sehingga koneksi gagal dengan kesalahan mendasar apa pun yang terjadi. Jika Anda memindahkan nama driver ke dalam extra_params sebagai gantinya, Anda akan mendapatkan kesalahan Reserved keyword 'driver'. Lihat mssql-python menolak opsi koneksi.

Solusi: Gunakan path pyodbc default jika alias harus menggunakan ODBC Driver 17 yang terpasang secara eksternal. Jalur mssql-python tidak kembali ke Driver 17, dan mengabaikan opsi tersebut driver . Jalur itu tidak memerlukan driver ODBC yang terpasang secara terpisah.

Koneksi ditolak

Gejala:

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

Kemungkinan penyebab dan solusi:

TCP/IP tidak diaktifkan pada SQL Server
- Buka Pengelola Konfigurasi SQL Server.
- Di bawah Konfigurasi Jaringan SQL Server, aktifkan TCP/IP.
- Di Properti TCP/IP, aktifkan alamat IP yang digunakan untuk koneksi.
- Mulai ulang layanan SQL Server.
Firewall memblokir port 1433
- Verifikasi bahwa aturan firewall mengizinkan koneksi masuk pada port 1433.
- Untuk Azure SQL, tambahkan IP klien Anda di pengaturan firewall portal Azure.
Nama atau port server yang salah

Verifikasi nilai HOST dan PORT dalam konfigurasi Anda.

Gejala:

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

Pada jalur mssql-python:

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

Kemungkinan penyebab dan solusi:

Kredensial yang salah

Verifikasi nama pengguna dan kata sandi.
Database di NAME tidak ada

Di SQL Server, jalur mssql-python menayangkan pesan yang sama OperationalError dengan kata sandi yang salah, jadi pesan itu saja tidak memberitahu mana yang Anda kena. Konfirmasi bahwa database sudah ada sebelum Anda mengubah kredensial. Arahkan NAME ke master untuk menguji login secara terpisah: jika koneksi berhasil, kredensial sudah benar dan masalahnya ada pada basis data. Path pyodbc melaporkan kasus ini secara terpisah sebagai Cannot open database "<database>" requested by the login. The login failed. (4060).

Azure SQL Database melaporkan kasus ini secara berbeda. Jalur mssql-python memunculkan Driver Error: General error; DDBC Error: [Microsoft][SQL Server]Cannot open server "<server>" requested by the login. The login failed. Pesan tersebut menyebutkan nama server, tetapi nama server tidak bermasalah. Periksa NAME sebagai gantinya.
Pengguna tidak ada

Pastikan login dipetakan ke akun pengguna di database target.
autentikasi SQL Server dinonaktifkan

Aktifkan autentikasi mode campuran, atau gunakan autentikasi Windows atau Microsoft Entra.

Waktu koneksi habis

Gejala:

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

Kemungkinan penyebab dan solusi:

Latensi jaringan

Tingkatkan connection_timeout di OPTIONS.
Azure SQL Database tanpa server dengan auto-pause diaktifkan

Database yang dijeda secara otomatis akan dilanjutkan kembali saat percobaan koneksi pertama, dan percobaan tersebut dapat gagal dengan kesalahan 40613 selama database dilanjutkan kembali. Atur connection_timeout ke minimal 60 dan coba ulang koneksi pertama. Untuk informasi lebih lanjut, lihat Azure SQL Database serverless dan Auto-pause serta auto-resume.

Server kelebihan beban

Tingkatkan connection_retries dan connection_retry_backoff_time.

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

Masalah migrasi

Kesalahan ini terjadi selama operasi migrasi Django terhadap SQL Server.

Masalah SQL mentah dan GROUP BY

Kesalahan ini terjadi ketika kueri mentah atau kueri beranotasi yang berisi klausa GROUP BY melewati langkah penulisan ulang placeholder di backend.

`IndexError` pada GROUP BY dengan `%%` yang di-escape dan parameter asli

Gejala:

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

Kueri berfungsi tanpa klausul GROUP BY dan tanpa literal %% yang di-escape, tetapi gagal ketika keduanya ada bersamaan dengan parameter %s yang sebenarnya.

Solusi: Upgrade ke rilis terbaru mssql-django . Backend mempersempit regex untuk menulis ulang placeholder hanya menjadi %% dan %s, sehingga literal %% yang di-escape dipertahankan apa adanya dan tidak ada placeholder semu yang disisipkan.

`NotImplementedError` untuk `IntegerChoices` dalam kueri GROUP BY mentah

Gejala:

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

Nilai enum yang sama berlaku pada kueri ORM dan kueri mentah tanpa GROUP BY, tetapi gagal ketika diteruskan sebagai parameter ke kueri mentah yang berisi klausa GROUP BY .

Solusi: Upgrade ke rilis terbaru mssql-django . Backend menggunakan isinstance untuk pemeriksaan tipe parameter dalam jalur GROUP BY, sehingga IntegerChoices (subkelas dari int) terikat dengan benar. bool masih mengikat bit, dan int biasa tidak berubah.

Masalah pencarian Regex

`regex` atau `iregex` tidak mengembalikan baris

Gejala: Kueri berjalan tanpa kesalahan dan mengembalikan set hasil kosong, meskipun baris sesuai dengan pola.

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

Penyebab: dbo.REGEXP_LIKE mengabaikan ruang kosong literal dalam pola. Polanya dicocokkan seolah-olah itu ^Widget\d+$, yang tidak dapat dipenuhi oleh nilai mana pun yang mengandung spasi. Tidak ada yang naik, jadi hasil kosong terlihat seperti masalah data.

Solusi: Tulis spasi putih sebagai escape atau kelas karakter:

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

`Cannot find ... dbo.REGEXP_LIKE`

Gejala:

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

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

Penyebab: Assembly CLR tidak terpasang di database yang Anda kueri. Itu diinstal per database, bukan per server.

Solusi: Jalankan python manage.py install_regex_clr <database> terhadap database tersebut. Jalankan ulang setelah menghapus dan membuat ulang database. Lihat Menyiapkan pencarian regex.

Masalah tanggal dan waktu

`Now()` nilai bergeser ketika `USE_TZ=True`

Gejala:

Tanda waktu yang ditulis dengan Django Now(), , auto_nowatau auto_now_add digeser ketika zona waktu host SQL Server bukan UTC.

Solusi: Upgrade ke rilis terbaru mssql-django . backend menghasilkan SQL yang mengetahui zona waktu Now(), mempertahankan offset datetimeoffset, dan membaca data zona waktu melalui zoneinfo dan tzdata.

`AttributeError` saat memanggil `.explain()`

Gejala:

AttributeError: ... explain_format ...

Solusi: Upgrade ke rilis terbaru mssql-django . Backend menangani metadata explain untuk setiap versi Django yang didukung.

Tidak dapat mengubah AutoField

Gejala:

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

Solusi: SQL Server tidak mendukung perubahan bidang dari atau ke AutoField. Buat model baru dengan jenis bidang yang diinginkan, migrasikan data secara manual, lalu letakkan tabel lama. Untuk solusinya, lihat Migrasi database dengan mssql-django.

Penggantian nama gagal karena batasan kunci asing

Gejala:

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

Solusi: SQL Server memerlukan penurunan batasan kunci asing sebelum mengganti nama kolom. Gunakan SeparateDatabaseAndState dalam migrasi Anda. Misalnya, lihat Migrasi database dengan mssql-django.

Masalah pengodean

Kesalahan pengkodean biasanya terjadi pada jalur pyodbc ketika pyodbc salah mengartikan data karakter dari SQL Server.

Kesalahan pengodean Unicode

Gejala:

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

Solusi: Konfigurasikan pyodbc pengkodean di OPTIONS kamus. Jalur mssql-python mengabaikan unicode_results.

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

Masalah FreeTDS

FreeTDS membutuhkan konfigurasi khusus pyodbc yang berbeda dari driver Microsoft ODBC.

kesalahan host_is_server

Gejala:

Koneksi gagal saat menggunakan FreeTDS tanpa menentukan host_is_server.

Solusi: Atur host_is_server ke True saat Anda menggunakan FreeTDS:

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

Untuk informasi selengkapnya tentang konfigurasi FreeTDS, lihat Opsi koneksi untuk mssql-django.

Menguji masalah database

Pembuatan dan penghancuran database pengujian dapat gagal tergantung pada metode autentikasi Anda.

Tidak dapat membuat database pengujian dengan identitas terkelola

Gejala:

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

Or:

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

Runner pengujian gagal membuat atau menghapus database pengujian saat Anda menggunakan autentikasi ActiveDirectoryMsi (identitas terkelola). Batasan ini ada karena:

Kredensial identitas terkelola diperoleh dari lingkungan host (seperti Azure VM dan App Service).
Pelari pengujian mencoba menyambungkan menggunakan kredensial database pengujian selama teardown.
Identitas terkelola dapat diberi peran pada tingkat database, tetapi pembuatan dan penghapusan database uji biasanya memerlukan izin tingkat server yang sering kali tidak dimiliki oleh runner pengujian.

Metode autentikasi yang terpengaruh:

ActiveDirectoryMsi(Azure identitas terkelola)
ActiveDirectoryServicePrincipal (bila hanya dikonfigurasi pada tingkat server)

Metode autentikasi yang didukung (pekerjaan pembuatan database pengujian):

ActiveDirectoryPassword
ActiveDirectoryIntegrated
Autentikasi SQL (nama pengguna/kata sandi)

Kompromi autentikasi untuk lingkungan pengujian

Metode	Tanpa rahasia	Mendukung pembuatan/penghapusan database pengujian secara otomatis	Kegunaan umum
`ActiveDirectoryMsi`	Yes	Biasanya tidak (kecuali hak akses tingkat server diberikan)	beban kerja produksi yang dihosting di Azure
`ActiveDirectoryServicePrincipal`	Tidak (rahasia/sertifikat klien)	Tergantung pada hak tingkat server yang diberikan	CI/CD dengan manajemen identitas eksplisit
`ActiveDirectoryPassword`	No	Ya (dengan izin SQL yang memadai)	Pengembang dan lingkungan CI terkontrol
Autentikasi SQL	No	Ya (dengan izin SQL yang memadai)	Lingkungan pengujian lokal atau terisolasi

Solusi:

Untuk pengembangan: Gunakan flag --keepdb untuk melewati pembongkaran database uji:
```
python manage.py test --keepdb
```

Untuk alur CI/CD: Buat database pengujian khusus sebelumnya dan berikan identitas CREATE TABLE dan ALTER izin terkelola:

-- 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: Gunakan autentikasi SQL untuk lingkungan pengujian, atau beralihlah ke ActiveDirectoryPassword untuk runner pengujian CI/CD.

Prosedur pemulihan

Saat migrasi gagal di tengah proses, gunakan urutan rollback ini untuk kembali ke kondisi stabil yang diketahui:

Hentikan penulisan aplikasi untuk menghindari penyimpangan skema tambahan.

Periksa status migrasi:

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

Gulung balik ke migrasi baik terakhir yang diketahui:

python manage.py migrate <app_label> <previous_migration>

Jika skema dan riwayat migrasi berbeda, perbaiki status dengan hati-hati menggunakan --fake hanya setelah memverifikasi skema database yang sebenarnya.
Jalankan kembali migrasi di lingkungan penahapan terlebih dahulu, lalu coba lagi produksi.

Important

Untuk migrasi destruktif seperti penghapusan, penggantian nama, dan perubahan tipe kolom, buat cadangan yang telah diuji sebelum penerapan. Jika rollback melalui migrasi tidak memungkinkan, pulihkan dari cadangan dan terapkan kembali migrasi yang telah divalidasi.

Masalah Docker dan kontainer

Image kontainer memerlukan instalasi driver ODBC secara eksplisit dan dependensi build saat Anda menggunakan jalur pyodbc bawaan. Jalur mssql-python tidak memiliki instalasi driver ODBC terpisah, tetapi tetap membutuhkan runtime unixODBC, karena backend mengimpor pyodbc saat Django memuatnya.

Driver ODBC tidak ditemukan dalam kontainer

Gejala:

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

Kemungkinan penyebab dan solusi:

Driver ODBC tidak diinstal dalam gambar kontainer

Image dasar Slim atau Alpine tidak menyertakan driver ODBC. Tambahkan repositori Microsoft APT dan instal msodbcsql18 di Dockerfile Anda saat menggunakan pyodbc. Lihat Menyebarkan ke App Service untuk contoh Dockerfile lengkap.
Paket hilang unixodbc-dev

Roda pyodbc terhubung dengan libodbc.so. Instal unixodbc-dev (Debian/Ubuntu) atau unixODBC-devel (RHEL/Fedora) sebelum menginstal paket Python.
apt-get autoremove dihapus libgssapi-krb5-2 setelah instalasi driver

msodbcsql18 memuat libgssapi-krb5-2 saat runtime tanpa mendeklarasikan sebagai dependensi. Pustaka ini biasanya disertakan sebagai dependensi dari curl, jadi menghapus curl dengan --auto-remove, atau menjalankan apt-get autoremove setelahnya, akan menghapusnya. Image berhasil dibangun tanpa error, tetapi semua koneksi kemudian gagal. Instal libgssapi-krb5-2 secara eksplisit, dan jangan hapus otomatis setelah driver diinstal.

Driver 17 dilaporkan hilang saat Anda menginstal versi 18

Gejala:

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

Kesalahan tersebut menamai versi 17, tetapi odbcinst -q -d menunjukkan versi 18 terdaftar dan dpkg -l msodbcsql18 menunjukkan bahwa versi tersebut terpasang.

Penyebab: Versi 18 terdaftar tetapi gagal dimuat, sehingga mssql-django kembali ke versi 17, yang tidak terinstal. Fallback melaporkan driver yang dicobanya sebagai opsi kedua, bukan driver yang gagal.

Solusi: Pasang libgssapi-krb5-2 dan bangun ulang. Lihat catatan autoremove sebelumnya untuk penjelasan tentang bagaimana pustaka tersebut bisa hilang.

Kesalahan saat memuat modul pyodbc dalam kontainer

Gejala:

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

Penyebab: Gambar tidak memiliki runtime unixODBC. mssql-django mengimpor pyodbc saat Django memuat backend, sehingga kesalahan ini juga terjadi pada jalur mssql-python, sebelum koneksi dicoba.

Solusi: Pasang unixodbc (atau unixodbc-dev).

driver mssql-python gagal dimuat

Gejala:

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

Penyebab: Driver yang disertakan dengan mssql-python memerlukan pustaka runtime Kerberos, yang tidak disertakan dalam image dasar slim.

Solusi: Instal libkrb5-3 dan libgssapi-krb5-2.

pyodbc gagal dikompilasi pada image slim

Gejala:

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

Or:

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

Solusi: Instal dependensi build sebelum pip install:

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

Atau, gunakan build bertahap untuk menjaga image akhir tetap kecil:

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

Kontainer tidak dapat tersambung ke SQL Server

Gejala:

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

Kemungkinan penyebab dan solusi:

Nama layanan Docker Compose tidak digunakan sebagai host

Saat menggunakan Docker Compose, atur DB_HOST ke nama layanan (misalnya, db), bukan localhost atau 127.0.0.1.

kontainer SQL Server belum siap

Kontainer SQL Server membutuhkan waktu beberapa detik untuk memulai. Tambahkan pemeriksaan kesehatan atau penundaan startup:

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

Konflik pemetaan port

Jika instans lain SQL Server berjalan pada host, ubah port yang diekspos (misalnya, 1434:1433) dan perbarui konfigurasi Django Anda yang sesuai.

Azure SQL pemulihan kesalahan sementara

Backend mssql-django secara otomatis mendeteksi koneksi Azure SQL Database dan Azure SQL Managed Instance dengan mengkueri SERVERPROPERTY('EngineEdition'). Saat berjalan dengan Azure SQL, sistem backend akan mencoba kembali koneksi saat terjadi error transien (seperti pembatasan sumber daya sementara atau gangguan jaringan singkat).

Anda dapat menyesuaikan perilaku ini dengan opsi connection_retries dan connection_retry_backoff_time:

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

Pengaturan ini hanya berlaku untuk pembentukan koneksi awal. Backend tidak mengulangi kueri yang gagal. Jika kueri gagal dengan kesalahan sementara setelah koneksi dibuat, pengecualian akan disebarluaskan ke kode aplikasi Anda. Gunakan logika coba lagi tingkat aplikasi (misalnya, django-retry-db atau middleware kustom) untuk ketahanan tingkat kueri.

Kueri lambat dan regresi rencana

Masalah ini biasanya memerlukan analisis sisi server bersama dengan tinjauan kueri tingkat Django.

Kueri menjadi lebih lambat atau mulai kehabisan waktu

Gejala:

Set kueri yang sama menjadi lebih lambat dari waktu ke waktu, atau mulai kehabisan waktu setelah pembaruan penyebaran, perubahan indeks, atau statistik.

Kemungkinan penyebab dan solusi:

Mulai dengan laporan performa bawaan

Untuk SQL Server dan Azure SQL Managed Instance, buka Dasbor Performa di SQL Server Management Studio. Untuk Azure SQL Database, buka Query Performance Insight untuk Azure SQL Database. Alat ini biasanya menjadi langkah awal yang lebih baik daripada kueri DMV ad hoc karena dapat dengan cepat mengungkap kueri yang mahal, waktu tunggu, dan tekanan pada sumber daya.
Merencanakan regresi

Gunakan Query Store untuk menemukan kueri yang lambat dan periksa apakah kueri tersebut memiliki beberapa rencana eksekusi. Mulailah dengan tampilan Kueri yang Diregresi dan Kueri Penggunaan Sumber Daya Teratas yang dijelaskan dalam Praktik terbaik untuk memantau beban kerja dengan Query Store.
Rencana eksekusi tidak efisien

Buka rencana eksekusi aktual untuk pernyataan dan periksa pemindaian tabel atau indeks, pencarian kunci besar, tumpahan hash, atau perkiraan baris yang tidak akurat. Untuk latar belakang, lihat Gambaran umum rencana eksekusi.
Hambatan yang salah diidentifikasi

Jika kueri tidak terikat CPU, gunakan statistik tunggu Query Store dan Identifikasi hambatan untuk membedakan CPU, memori, I/O disk, pemblokiran, dan tekanan koneksi.
Perbaikan diterapkan di lapisan yang salah

Terapkan perbaikan paling kecil yang tetap efektif: tambahkan atau sesuaikan indeks, perbarui statistik, kurangi jumlah kolom dan baris yang dipilih, atau lakukan penulisan data besar secara batch. Jika Anda memerlukan mitigasi darurat, DBA dapat untuk sementara memaksakan rencana eksekusi yang telah terbukti baik di dalam Query Store selagi Anda memperbaiki penyebab utamanya.

Menggunakan dbshell untuk kueri interaktif

Perintah manajemen Django dbshell membuka shell SQL interaktif yang tersambung ke database Anda:

python manage.py dbshell

Backend menggunakan sqlcmd saat Anda mengonfigurasi driver MICROSOFT ODBC, atau isql saat Anda menggunakan FreeTDS. Pastikan alat tersebut ada di PATH Anda:

Windows: sqlcmd disertakan dengan alat SQL Server, atau Anda dapat mengunduhnya secara terpisah.
Linux dan macOS: Instal mssql-tools18 dari repositori Microsoft.

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-10-17

Memecahkan masalah mssql-django

Masalah koneksi

Driver ODBC tidak ditemukan di jalur pyodbc

mssql-python menolak opsi koneksi

dependensi mssql-python terlalu usang

Mekanisme fallback Driver 17 tidak diterapkan pada mssql-python

Koneksi ditolak

Gagal masuk

Waktu koneksi habis

Masalah migrasi

Masalah SQL mentah dan GROUP BY

IndexError pada GROUP BY dengan %% yang di-escape dan parameter asli

NotImplementedError untuk IntegerChoices dalam kueri GROUP BY mentah

Masalah pencarian Regex

__regex atau __iregex tidak mengembalikan baris

Cannot find ... dbo.REGEXP_LIKE

Masalah tanggal dan waktu

Now() nilai bergeser ketika USE_TZ=True

AttributeError saat memanggil .explain()

Tidak dapat mengubah AutoField

Penggantian nama gagal karena batasan kunci asing

Masalah pengodean

Kesalahan pengodean Unicode

Masalah FreeTDS

kesalahan host_is_server

Menguji masalah database

Tidak dapat membuat database pengujian dengan identitas terkelola

Kompromi autentikasi untuk lingkungan pengujian

Prosedur pemulihan

Masalah Docker dan kontainer

Driver ODBC tidak ditemukan dalam kontainer

Driver 17 dilaporkan hilang saat Anda menginstal versi 18

Kesalahan saat memuat modul pyodbc dalam kontainer

driver mssql-python gagal dimuat

pyodbc gagal dikompilasi pada image slim

Kontainer tidak dapat tersambung ke SQL Server

Azure SQL pemulihan kesalahan sementara

Kueri lambat dan regresi rencana

Kueri menjadi lebih lambat atau mulai kehabisan waktu

Menggunakan dbshell untuk kueri interaktif

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan:

`IndexError` pada GROUP BY dengan `%%` yang di-escape dan parameter asli

`NotImplementedError` untuk `IntegerChoices` dalam kueri GROUP BY mentah

`regex` atau `iregex` tidak mengembalikan baris

`Cannot find ... dbo.REGEXP_LIKE`

`Now()` nilai bergeser ketika `USE_TZ=True`

`AttributeError` saat memanggil `.explain()`