mssql-python sürücüsü, SQL Server ve Azure SQL için standart bir istisna hiyerarşisi, yaygın hata işleme desenleri ve SQLSTATE kod eşlemeleri tanımlar.
Özel durum hiyerarşisi
mssql-python sürücüsü, DB-API 2.0 (PEP 249) istisna hiyerarşisini takip eder:
Exception (builtins)
├── Warning
└── Error
├── InterfaceError
└── DatabaseError
├── DataError
├── OperationalError
├── IntegrityError
├── InternalError
├── ProgrammingError
└── NotSupportedError
ConnectionStringParseError (standalone, not part of hierarchy)
İstisna açıklamaları
Durumunuza en uygun istisnayı yakalayın. Örneğin, /UPDATE işlemler üzerindeki kısıtlama ihlalleri INSERTve ProgrammingError geliştirme sırasında SQL sözdizimi sorunları için yakalamaIntegrityError. Sadece temel Error sınıfı yedek olarak yakaladım.
| Exception |
Yükseltildiğinde |
Warning |
Veritabanından ölümcül olmayan uyarılar. |
Error |
Tüm veritabanı hataları için temel sınıf. |
InterfaceError |
Hatalar veritabanı arayüzüyle (sürücü) ilgili, veritabanının kendisiyle değil. |
DatabaseError |
Veritabanıyla ilgili hatalar. |
DataError |
İşlenen verilerle ilgili sorunlardan kaynaklanan hatalar (sıfıra bölünme, değer aralık dışında). |
OperationalError |
Veritabanı işlemleriyle ilgili hatalar (bağlantı kaybı, bellek tahsisi, işlem hataları). |
IntegrityError |
Veritabanı bütünlüğü etkilendiğinde hatalar (yabancı anahtar ihlali, benzersiz kısıtlama). |
InternalError |
İç veritabanı hataları (imleç geçerli değil, işlem senkronize değil). |
ProgrammingError |
Programlama hataları (sözdizimi hataları, tablo bulunamadı, yanlış sayıda parametre). |
NotSupportedError |
Özellik veritabanı veya sürücü tarafından desteklenmiyor. |
ConnectionStringParseError |
Geçersiz bağlantı dizesi sözdizimi veya bilinmeyen anahtar kelimeler. |
Temel hata yönetimi
Veritabanı hatalarını yönetmek için deneme blokları kullanın:
import mssql_python
try:
conn = mssql_python.connect(connection_string)
cursor = conn.cursor()
cursor.execute("INSERT INTO Production.Product (Name) VALUES (%(name)s)", {"name": "Test"})
conn.commit()
except mssql_python.IntegrityError as e:
print(f"Constraint violation: {e}")
conn.rollback()
except mssql_python.ProgrammingError as e:
print(f"SQL syntax error: {e}")
except mssql_python.OperationalError as e:
print(f"Connection or operational error: {e}")
except mssql_python.Error as e:
print(f"Database error: {e}")
finally:
if 'conn' in locals():
conn.close()
Bağlantı üzerinden erişim istisnaları
İstisnaları bağlantı örneği üzerinden yakalayabilirsiniz:
try:
cursor.execute("INVALID SQL")
except conn.ProgrammingError as e:
print(f"Caught via connection: {e}")
Hata mesajı yapısı
MSSQL-python istisna nesneleri, sürücünün Exception temel sınıfından gelen üç özniteliği ortaya çıkarır:
| Attribute |
Source |
Açıklama |
driver_error |
Python sürücüsü |
SQLSTATE tarafından seçilen standart İngilizce metin ODBC'den dönerdi (örneğin, "Communication link failure", "Invalid authorization specification", "Syntax error or access violation"). Yayınlar arasında istikrarlı; alt sare eşleşmesi güvenli bir yöntem. |
ddbc_error |
Doğrudan Veritabanı Bağlantısı (DDBC) |
Sunucu tarafı mesajı, genellikle ön ekte .[Microsoft][SQL Server] Format istikrarlı bir sözleşme değildir. |
message |
Oluşan |
f"Driver Error: {driver_error}; DDBC Error: {ddbc_error}". İşte geri dönen str(exc) şey bu. |
try:
cursor.execute("SELECT * FROM no_such_table;")
except mssql_python.ProgrammingError as exc:
print(exc.driver_error) # Base table or view not found
print(exc.ddbc_error) # [Microsoft][SQL Server]Invalid object name 'no_such_table'.
print(exc) # Driver Error: Base table or view not found; DDBC Error: ...
SQL Server motoru hata numarası (örneğin 208 veya 40501) bir öznitelik olarak açığa çıkmaz ve her iki dizeye de güvenilir şekilde gömülü değildir. Hataları istisna alt sınıfı artı driver_error metne göre sınıflandırın. Azure SQL throttling için bkz. Retry logic.
SQLSTATE sınıflandırması
mssql-python, hem Python istisna alt sınıfını hem driver_error de metni seçmek için ODBC tarafından döndürülen SQLSTATE kullanır. Tam SQLSTATE → istisna eşlemesi sürücü kaynağında yer alır exceptions.py . Bir sonraki bölüm, SQL Server ve Azure SQL ile en sık görülen SQLSTATE'leri listeler.
Bağlantı hataları
Yükseltmeden mssql_python.OperationalErrorkaynaklanan mssql_python.connect() bağlantı arızaları, diğer bağlantı arızalarıyla aynı:
import mssql_python
try:
conn = mssql_python.connect(
"Server=unreachable-server.database.windows.net;"
"Database=<database>;"
"Authentication=ActiveDirectoryDefault;"
"Encrypt=yes"
)
except mssql_python.OperationalError as e:
print(f"Connection failed: {e.driver_error}")
# e.driver_error: "Client unable to establish connection"
Bağlantı dizesi hataları
Bağlantı dizisi ayrıştırma hataları :ConnectionStringParseError
try:
conn = mssql_python.connect("Servr=localhost;") # Typo
except mssql_python.ConnectionStringParseError as e:
print(f"Invalid connection string: {e}")
# Output: Unknown keyword 'Servr'
SQLSTATE kod referansı
SQLSTATE kodları, hata koşullarını belirleyen beş karakterli kodlardır. İlk iki karakter sınıfı, son üçü ise alt sınıfı gösterir. Bu kodları nadiren doğrudan incelemenize ihtiyacınız olur. Bunun yerine, uygun Python istisna tipini ("İstisna" sütununda listelenmiş) yakalayın Aynı istisna tipinde belirli hata koşullarını ayırt etmek için SQLSTATE kodlarını kullanın; örneğin deadlock (40001) ile genel bağlantı hatası (08S01) arasındaki ayrım için.
Sınıf 00 - Başarılı tamamlama
| SQLSTATE |
Exception |
Açıklama |
| 00000 |
Hiçbiri |
Success |
Sınıf 01 - Uyarı
| SQLSTATE |
Exception |
Açıklama |
| 01000 |
Warning |
Genel uyarı |
| 01001 |
Warning |
İmleç işlemi çakışması |
| 01002 |
Warning |
Bağlantı Bırakma Hatası |
| 01003 |
DataError |
Küme işlevinde null değer ortadan kaldırıldı |
| 01004 |
DataError |
Dize verileri, sağa kesme |
| 01006 |
Warning |
Ayrıcalık iptal edilmiyor |
| 01007 |
Warning |
Ayrıcalık verilmedi |
| 01S00 |
Warning |
Geçersiz bağlantı dizesi özniteliği |
| 01S01 |
Warning |
Sırada hata |
| 01S02 |
Warning |
Seçenek değeri değiştirildi |
Sınıf 07 - Dinamik SQL hatası
| SQLSTATE |
Exception |
Açıklama |
| 07001 |
ProgrammingError |
Yanlış sayıda parametre |
| 07002 |
ProgrammingError |
COUNT alanı yanlış |
| 07005 |
ProgrammingError |
Hazırlanmış ifade, bir imleç belirtisi değil |
| 07006 |
ProgrammingError |
Kısıtlanmış veri türü özniteliği ihlali |
| 07009 |
ProgrammingError |
Geçersiz tanımlayıcı indeksi |
| 07S01 |
ProgrammingError |
Varsayılan parametrenin geçersiz kullanımı |
Sınıf 08 - Bağlantı istisnası
| SQLSTATE |
Exception |
Açıklama |
| 08001 |
OperationalError |
İstemci bağlantı kuramıyor |
| 08002 |
OperationalError |
Bağlantının adı kullanımda |
| 08003 |
OperationalError |
Bağlantı yoktur |
| 08004 |
OperationalError |
Sunucu bağlantıyı reddetti |
| 08007 |
OperationalError |
İşlem sırasında bağlantı arızası |
| 08S01 |
OperationalError |
İletişim bağlantısı hatası |
Sınıf 21 - Kardinalet ihlali
| SQLSTATE |
Exception |
Açıklama |
| 21S01 |
ProgrammingError |
Değer listesi, sütun listesiyle eşleşmiyor |
| 21S02 |
ProgrammingError |
Türetilmiş tablonun derecesi sütun listesiyle eşleşmiyor |
Sınıf 22 - Veri istisnası
| SQLSTATE |
Exception |
Açıklama |
| 22001 |
DataError |
Dize verileri, sağa kesme |
| 22002 |
DataError |
Gösterge değişkeni gerekli ancak sağlanmadı |
| 22003 |
DataError |
Sayısal değer aralık dışında |
| 22007 |
DataError |
Geçersiz tarih saat biçimi |
| 22008 |
DataError |
Tarih saat alanı taşması |
| 22012 |
DataError |
Sıfıra bölme |
| 22015 |
DataError |
Aralık alanı taşması |
| 22018 |
DataError |
Atama belirtimi için geçersiz karakter değeri |
| 22019 |
DataError |
Geçersiz çıkış karakteri |
| 22025 |
DataError |
Geçersiz çıkış sırası |
| 22026 |
DataError |
Dize verileri, uzunluk uyuşmazlığı |
Sınıf 23 - Bütünlük kısıtlaması ihlali
| SQLSTATE |
Exception |
Açıklama |
| 23000 |
IntegrityError |
Bütünlük kısıtlaması ihlali (genel) |
Sınıf 24 - Geçersiz imleç durumu
| SQLSTATE |
Exception |
Açıklama |
| 24000 |
Dahili Hata |
Geçersiz imleç durumu |
Sınıf 25 - Geçersiz işlem durumu
| SQLSTATE |
Exception |
Açıklama |
| 25000 |
OperationalError |
Geçersiz işlem durumu |
| 25S01 |
OperationalError |
İşlem durumu bilinmiyor |
| 25S02 |
OperationalError |
İşlem hâlâ aktif |
| 25S03 |
OperationalError |
İşlem geri alınır |
Sınıf 28 - Geçersiz yetkilendirme spesifikasyonu
| SQLSTATE |
Exception |
Açıklama |
| 28000 |
OperationalError |
Geçersiz yetkilendirme belirtisi (giriş başarısız oldu) |
Sınıf 34 - Geçersiz imleç adı
| SQLSTATE |
Exception |
Açıklama |
| 34000 |
ProgrammingError |
Geçersiz imleç adı |
Sınıf 3C - Tekrarlanan imleç adı
| SQLSTATE |
Exception |
Açıklama |
| 3C000 |
ProgrammingError |
Yinelenen imleç adı |
Sınıf 3D - Geçersiz katalog adı
| SQLSTATE |
Exception |
Açıklama |
| 3D000 |
ProgrammingError |
Geçersiz katalog adı |
Sınıf 3F - Geçersiz şema adı
| SQLSTATE |
Exception |
Açıklama |
| 3F000 |
ProgrammingError |
Geçersiz şema adı |
Sınıf 40 - İşlemin geri alınması
| SQLSTATE |
Exception |
Açıklama |
| 40001 |
OperationalError |
Serileştirme hatası (çıkmaz) |
| 40002 |
OperationalError |
Bütünlük kısıtlaması ihlali geri almaya neden oldu |
| 40003 |
OperationalError |
Deyim tamamlama bilinmiyor |
Sınıf 42 - Sözdizimi hatası veya erişim kuralı ihlali
| SQLSTATE |
Exception |
Açıklama |
| 42000 |
ProgrammingError |
Söz dizimi hatası veya erişim ihlali |
| 42S01 |
ProgrammingError |
Temel tablo veya görünüm zaten var |
| 42S02 |
ProgrammingError |
Temel tablo veya görünüm bulunamadı |
| 42S11 |
ProgrammingError |
Dizin zaten var |
| 42S12 |
ProgrammingError |
Dizin bulunamadı |
| 42S21 |
ProgrammingError |
Sütun zaten var |
| 42S22 |
ProgrammingError |
Sütun bulunamadı |
Sınıf 44 - KONTROL SEÇİCİ İHLALI
| SQLSTATE |
Exception |
Açıklama |
| 44000 |
IntegrityError |
CHECK OPTION ihlali ILE |
HY sınıfı - CLI'ye özgü durum
| SQLSTATE |
Exception |
Açıklama |
| HY000 |
DatabaseError |
Genel hata |
| HY001 |
OperationalError |
Bellek ayırma hatası |
| HY003 |
ProgrammingError |
Geçersiz uygulama tamponu türü |
| HY004 |
ProgrammingError |
Geçersiz SQL veri tipi |
| HY007 |
ProgrammingError |
İlgili ifade hazırlanmamıştır |
| HY008 |
OperationalError |
İşlem iptal edildi |
| HY009 |
ProgrammingError |
Geçersiz null işaretçi kullanımı |
| HY010 |
ProgrammingError |
İşlev dizisi hatası |
| HY011 |
ProgrammingError |
Öznitelik şu anda ayarlanamaz |
| HY012 |
ProgrammingError |
Geçersiz işlem işlem kodu |
| HY013 |
OperationalError |
Bellek yönetimi hatası |
| HY014 |
OperationalError |
Aşılmış tutamaçlar sayısı sınırı |
| HY015 |
ProgrammingError |
İmleç adı mevcut değil |
| HY016 |
ProgrammingError |
Bir uygulama satır tanımlayıcısını değiştiremiyor |
| HY017 |
ProgrammingError |
Otomatik tahsis edilmiş tanımlayıcı kolunun geçersiz kullanımı |
| HY018 |
OperationalError |
Sunucu iptal başvurusunu reddetti |
| HY019 |
ProgrammingError |
Parça halinde gönderilen karakter dışı ve ikili olmayan veriler |
| HY020 |
DataError |
Null değeri birleştirmeye çalış |
| HY021 |
ProgrammingError |
Tutarsız tanımlayıcı bilgisi |
| HY024 |
ProgrammingError |
Geçersiz öznitelik değeri |
| HY090 |
ProgrammingError |
Geçersiz dize veya arabellek uzunluğu |
| HY091 |
ProgrammingError |
Geçersiz tanımlayıcı alan tanımlayıcısı |
| HY092 |
ProgrammingError |
Geçersiz öznitelik/seçenek tanımlayıcısı |
| HY095 |
ProgrammingError |
Fonksiyon tipi menzil dışı |
| HY096 |
ProgrammingError |
Geçersiz bilgi türü |
| HY097 |
ProgrammingError |
Menzil dışı sütun tipi |
| HY098 |
ProgrammingError |
Menzil dışı dürbün türü |
| HY099 |
ProgrammingError |
Nullable tip menzil dışı |
| HY100 |
ProgrammingError |
Benzersizlik seçeneği türü aralık dışında |
| HY101 |
ProgrammingError |
Doğruluk seçeneği türü aralık dışında |
| HY103 |
ProgrammingError |
Geçersiz erişim kodu |
| HY104 |
ProgrammingError |
Geçersiz hassasiyet veya ölçek değeri |
| HY105 |
ProgrammingError |
Geçersiz parametre türü |
| HY106 |
ProgrammingError |
Menzil dışı tıp getir |
| HY107 |
ProgrammingError |
Satır değeri aralık dışı |
| HY109 |
ProgrammingError |
Geçersiz imleç konumu |
| HY110 |
ProgrammingError |
Geçersiz sürücü tamamlanması |
| HY111 |
ProgrammingError |
Geçersiz yer imimi değeri |
| HYC00 |
NotSupportedError |
İsteğe bağlı özellik uygulanmadı |
| HYT00 |
OperationalError |
Zaman aşımı süresi doldu |
| HYT01 |
OperationalError |
Bağlantı zaman aşımı süresi doldu |
Sınıf IM - Sürücü yöneticisi hatası
| SQLSTATE |
Exception |
Açıklama |
| IM001 |
Arayüz Hatası |
Sürücü bu işlevi desteklemiyor |
| IM002 |
Arayüz Hatası |
Veri kaynağı adı bulunamadı |
| IM003 |
Arayüz Hatası |
Belirtilen sürücü yüklenemedi. |
| IM004 |
Arayüz Hatası |
Driver'ın SQLAllocHandle SQL_HANDLE_ENV üzerinde başarısız oldu |
| IM005 |
Arayüz Hatası |
Sürücünün SQLAllocHandle SQL_HANDLE_DBC üzerinde başarısız oldu |
| IM006 |
Arayüz Hatası |
Driver'ın SQLSetConnectAttr başarısız oldu |
| IM007 |
Arayüz Hatası |
Veri kaynağı veya sürücü belirtilmedi |
| IM008 |
Arayüz Hatası |
Diyalog başarısız oldu |
| IM009 |
Arayüz Hatası |
Çeviri DLL'i yüklenemez |
| IM010 |
Arayüz Hatası |
Veri kaynağı adı çok uzun |
| IM011 |
Arayüz Hatası |
Sürücü adı çok uzun |
| IM012 |
Arayüz Hatası |
DRIVER anahtar kelime sözdizimi hatası |
| IM014 |
Arayüz Hatası |
Geçersiz DSN |
| IM015 |
Arayüz Hatası |
Bozuk dosya veri kaynağı |
Yaygın SQL Server hata sayıları
SQLSTATE'in ötesinde, SQL Server yerel hata sayılarını parantez içinde sunar. Uygulama kodunda karşılaşma olasılığınızın en yüksek olduğu hatalar bunlardır. Yeniden deneme mantığını, 1205 hatası (deadlock) ve geçici bağlantı hataları etrafında inşa edin ( bkz. Yeniden deneme mantığı).
| Error |
İleti düzeni |
Çözünürlük |
| 208 |
Geçersiz nesne adı |
Tablonun veya görünümün var olup olmadığını doğrulayın ve şema niteliklendirmesini kontrol edin. |
| 547 |
Kısıtlama ihlali |
Yabancı bir anahtar veya kontrol kısıtlaması başarısız oldu. |
| 2627 |
Benzersiz kısıtlama ihlali |
Bir tekrarlanan anahtar değeri eklendi. |
| 2601 |
Benzersiz indeks ihlali |
İndekste bir kopya anahtar vardır. |
| 4060 |
Veritabanı açılamıyor |
Veritabanı yok ya da erişim reddediliyor. |
| 18456 |
Oturum açılamadı |
Kimlik doğrulama hatası. Kimlik bilgilerini kontrol edin. |
| 1205 |
Kilitlenme kurbanı |
İşlem geri alındı. İşlemi yeniden deneyin. |
Simptom-to-exception hızlı referans
Bu tabloyu kullanarak yaygın semptomları yakalamanız gereken istisna türüne eşleyin:
| Belirti |
Exception |
Olası neden |
| "Kullanıcı için giriş başarısız oldu" |
OperationalError |
Yanlış kimlik bilgileri veya kullanıcı veritabanına eşlenmemiş. |
| "İstemci bağlantı kuramıyor" |
OperationalError |
Sunucuya ulaşılamıyor, güvenlik duvarı veya DNS sorunu var. |
| "Mola süresi doldu" |
OperationalError |
Sorgu veya bağlantı süresi. Zaman aşımını artırın veya sorguyu optimize edin. |
| "Geçersiz nesne adı" |
ProgrammingError |
Tablo yok ya da şema belirtilmemiş. |
| "Yanlış sözdizim" |
ProgrammingError |
SQL sözdizimi hatası. SSMS'de test sorgusu. |
| "Yanlış sayıda parametre" |
ProgrammingError |
Parametre sayısı yer tutucularla eşleşmiyor. |
| "BIRINCIL ANAHTAR İhlali" |
IntegrityError |
Anahtarı kopyala. Yerleştirmeden önce kullanın MERGE veya kontrol edin. |
| "YABANCI ANAHTARIN İhlali" |
IntegrityError |
Referanslı bir sıra yok. Önce ebeveyni ekle. |
| "İşlem çıkmazdaydı" |
OperationalError (hata 1205) |
Kilit mücadelesi. Yeniden deneme mantığını uygulayın. |
| "Dize veya ikili veri kesilir" |
DataError |
Değer sütun uzunluğunu aşmaktadır. Verileri kontrol edin veya sütun boyutunu artırın. |
| "Dönüşüm başarısız oldu" |
DataError |
Tür uyuşmazlığı. Sütun için doğru Python tipini kullanın. |
| "Bilinmeyen anahtar kelime" |
ConnectionStringParseError |
bağlantı dizesi anahtar kelimesinde yazım hatası. |
| "callproc desteklenmiyor" |
NotSupportedError |
Bunun yerine cursor.execute("EXECUTE ...") kullanın. |
En iyi uygulamalar
-
Genel istisnalardan önce belirli istisnaları yakala . En özel (
IntegrityError) ile en az spesifik (Error) arasındaki sıra.
- Veri değiştirme işlemleri için her zaman IntegrityError ile ilgilenin. Kısıtlama ihlalleri normal operasyonda beklenir (örneğin, bir kullanıcı tekrarı bir kullanıcı adı oluşturmaya çalışırsa).
- Sorun giderme için tam hata bağlamını kaydedin. İstisna,
driver_error (kararlı, SQLSTATE-türevli metin) ve ddbc_error (sunucu tarafı mesajı) açığa çıkarır. İkisini de kaydet; Sınıflandırma .driver_error
- Geçici hatalar (bağlantı arızaları, çıkmazlar) için yeniden deneme mantığı uygulan. Bkz . Yeniden deneme mantığı.
- Başarısız işlemleri temizlemek için istisna işleyicilerinde rollback() kullanın. Açık bir geri alma olmadan, bağlantı başarısız işlem durumunda kalır.
İlgili içerik