Az mssql-python illesztőprogram szabványos kivételhierarchiát, gyakori hibakezelési mintákat, valamint SQLSTATE kódleképezéseket határoz meg az SQL Server és Azure SQL számára.
Kivételhierarchia
Az mssql-python illesztőprogram a DB-API 2.0 (PEP 249) kivételhierarchiáját követi:
Exception (builtins)
├── Warning
└── Error
├── InterfaceError
└── DatabaseError
├── DataError
├── OperationalError
├── IntegrityError
├── InternalError
├── ProgrammingError
└── NotSupportedError
ConnectionStringParseError (standalone, not part of hierarchy)
Kivételek leírásai
Találd meg a legpontosabb kivételt, ami megfelel a helyzetednek. Például IntegrityError a korlátozások megsértése esetén / INSERTUPDATE műveletek esetén, valamint ProgrammingError SQL szintaxissal kapcsolatos problémák fejlesztés közben. Csak tartalékként kapd meg az alap Error osztályt.
| Exception |
Amikor felemelik |
Warning |
Nem halálos figyelmeztetések az adatbázisból. |
Error |
Alap osztály minden adatbázis hibához. |
InterfaceError |
A hibák az adatbázis interfészéhez (driverhez) kapcsolódnak, nem magához az adatbázishoz. |
DatabaseError |
Adatbázissal kapcsolatos hibák. |
DataError |
Hibák a feldolgozott adatokkal kapcsolatos problémák miatt (nullával osztás, érték a tartományon kívül). |
OperationalError |
Az adatbázis működésével kapcsolatos hibák (kapcsolat elvesztése, memória levonás, tranzakciós hibák). |
IntegrityError |
Hibák, amikor az adatbázis integritása sérül (idegen kulcs megsértése, egyedi korlátozás). |
InternalError |
Belső adatbázis hibák (kurzor nem érvényes, tranzakció nincs szinkron). |
ProgrammingError |
Programozási hibák (szintaxishiba, táblázat nem található, hibás számú paraméter). |
NotSupportedError |
A funkció nem támogat az adatbázis vagy az illezőprogram. |
ConnectionStringParseError |
Érvénytelen kapcsolati karakterlánc szintaxis vagy ismeretlen kulcsszavak. |
Alapvető hibakezelés
Próbálkozzon blokkokat az adatbázis hibáinak kezelésére:
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()
Hozzáférési kivételek a kapcsolaton keresztül
Kivételeket a kapcsolati példányon keresztül lehet elkapni:
try:
cursor.execute("INVALID SQL")
except conn.ProgrammingError as e:
print(f"Caught via connection: {e}")
Hibaüzenet szerkezete
Az MSSQL-python kivételobjektumok három attribútumot tárnak fel, amelyek az illesztőprogram Exception alaposztályából származnak:
| Attribute |
Source |
Leírás |
driver_error |
Python driver |
Az SQLSTATE által kiválasztott szabványosított angol szöveg az ODBC-ből származik (például "Communication link failure", "Invalid authorization specification", "Syntax error or access violation"). Stabil a kiadások között; biztonságos alhúros párosításra. |
ddbc_error |
Közvetlen adatbázis-kapcsolat (DDBC) |
A szerveroldali üzenet, amely általában az előtaggal [Microsoft][SQL Server]áll. A formátum nem stabil szerződés. |
message |
Összetevőkből áll |
f"Driver Error: {driver_error}; DDBC Error: {ddbc_error}". Ez az, ami str(exc) visszatér. |
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: ...
Az SQL Server motor hibaszáma (például 208 vagy 40501) nincs elérhető attribútumként, és egyik stringben sem van megbízhatóan beágyazva. Osztályozz hibákat kivétel alosztály és driver_error szöveg szerint. Azure SQL throttling esetén lásd: Retry logic.
SQLSTATE osztályozás
Az mssql-python az ODBC által visszaadott SQLSTATE-t használja mind a Python kivételosztály, mind a driver_error szöveg kiválasztásához. A teljes SQLSTATE → exception leképezés a meghajtó forrásában található exceptions.py . A következő rész felsorolja azokat az SQLSTATE-eket, amelyek leggyakrabban az SQL Server-ben és az Azure SQL-ben jelennek meg.
Csatlakozási hibák
Csatlakozási hibák a mssql_python.connect() felhajtásból mssql_python.OperationalError, ugyanúgy, mint más kapcsolódási hibák:
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"
Csatlakozási karakterlánc hibák
A kapcsolati lánc elemzési hibák :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 kód referencia
Az SQLSTATE kódok ötkarakteres kódok, amelyek hibakörülményeket azonosítanak. Az első két karakter az osztályt, az utolsó három pedig az alosztályt. Ritkán kell közvetlenül ellenőrizni ezeket a kódokat. Ehelyett kapd meg a megfelelő Python kivételtípust (amely a "Kivétel" oszlopban található). Használj SQLSTATE kódokat, amikor meg kell különböztetned a konkrét hibafeltételeket ugyanabban a kivételtípusban, például hogy megkülönböztesd a holtpontot (40001) egy általános kapcsolati hibától (08S01).
00-as osztály – Sikeres befejezés
| SQLSTATE |
Exception |
Leírás |
| 00000 |
None |
Success |
01-es osztály - Figyelmeztetés
| SQLSTATE |
Exception |
Leírás |
| 01000 |
Warning |
Általános figyelmeztetés |
| 01001 |
Warning |
Kurzorművelet ütközése |
| 01002 |
Warning |
Megszakítás hiba |
| 01003 |
DataError |
NULL érték a készletfüggvényben |
| 01004 |
DataError |
Karakterlánc, jobb oldali csonkítás |
| 01006 |
Warning |
A jogosultság nincs visszavonva |
| 01007 |
Warning |
A jogosultság nincs megadva |
| 01S00 |
Warning |
Invalid kapcsolati karakterlánc attribútum |
| 01S01 |
Warning |
Hiba a sorban |
| 01S02 |
Warning |
A beállítás értéke módosult |
07. osztály - Dinamikus SQL hiba
| SQLSTATE |
Exception |
Leírás |
| 07001 |
ProgrammingError |
Rossz számú paraméter |
| 07002 |
ProgrammingError |
A DARAB mező helytelen |
| 07005 |
ProgrammingError |
Előkészített kijelentés, nem kurzor-specifikáció |
| 07006 |
ProgrammingError |
Korlátozott adattípus-attribútumok megsértése |
| 07009 |
ProgrammingError |
Érvénytelen descriptor index |
| 07S01 |
ProgrammingError |
Az alapértelmezett paraméter használata érvénytelen |
08. osztály – Csatlakozási kivétel
| SQLSTATE |
Exception |
Leírás |
| 08001 |
OperationalError |
Az ügyfél nem tudja kapcsolatot teremteni |
| 08002 |
OperationalError |
Használatban lévő kapcsolatnév |
| 08003 |
OperationalError |
Kapcsolat nem létezik |
| 08004 |
OperationalError |
A szerver elutasította a kapcsolatot |
| 08007 |
OperationalError |
Kapcsolati hiba tranzakció közben |
| 08S01 |
OperationalError |
Kommunikációs kapcsolat hibája |
21. osztály – Kardinalitás megsértése
| SQLSTATE |
Exception |
Leírás |
| 21S01 |
ProgrammingError |
Az értéklista beszúrása nem egyezik az oszloplistával |
| 21S02 |
ProgrammingError |
A származtatott tábla mértéke nem egyezik az oszloplistával |
22. osztály - Adatkivétel
| SQLSTATE |
Exception |
Leírás |
| 22001 |
DataError |
Karakterlánc, jobb oldali csonkítás |
| 22002 |
DataError |
A mutatóváltozó kötelező, de nincs megadva |
| 22003 |
DataError |
Numerikus érték a tartományon kívül |
| 22007 |
DataError |
Érvénytelen dátum/idő formátum |
| 22008 |
DataError |
Datetime mező túlcsordul |
| 22012 |
DataError |
Osztás nullával |
| 22015 |
DataError |
Intervallummező túlcsordult |
| 22018 |
DataError |
Érvénytelen karakterérték az öntött specifikációhoz |
| 22019 |
DataError |
Érvénytelen feloldó karakter |
| 22025 |
DataError |
Érvénytelen feloldási sorozat |
| 22026 |
DataError |
Sztringadatok, hosszeltérés |
23. osztály – Integritási korlátozás megsértése
| SQLSTATE |
Exception |
Leírás |
| 23000 |
IntegrityError |
Integritási korlátozás megsértése (általános) |
24. osztály - Érvénytelen kurzorállapot
| SQLSTATE |
Exception |
Leírás |
| 24000 |
Belső hiba |
Érvénytelen kurzorállapot |
25. osztály - Érvénytelen tranzakciós állapot
| SQLSTATE |
Exception |
Leírás |
| 25000 |
OperationalError |
Érvénytelen tranzakciós állapot |
| 25S01 |
OperationalError |
Tranzakciós állapot ismeretlen |
| 25S02 |
OperationalError |
A tranzakció továbbra is aktív |
| 25S03 |
OperationalError |
A tranzakció visszafordítva van |
28. osztály - Érvénytelen engedélyezési specifikáció
| SQLSTATE |
Exception |
Leírás |
| 28000 |
OperationalError |
Érvénytelen authorization specification (bejelentkezés hibás) |
34. osztály - Érvénytelen kurzornév
| SQLSTATE |
Exception |
Leírás |
| 34000 |
ProgrammingError |
Érvénytelen kurzornév |
3C osztály - Duplán kurzornév
| SQLSTATE |
Exception |
Leírás |
| 3C000 |
ProgrammingError |
Ismétlődő kurzornév |
3D osztály - Érvénytelen katalógusnév
| SQLSTATE |
Exception |
Leírás |
| 3D000 |
ProgrammingError |
Érvénytelen katalógusnév |
3F osztály - Érvénytelen séma név
| SQLSTATE |
Exception |
Leírás |
| 3F000 |
ProgrammingError |
Érvénytelen sémanév |
40. osztály – Tranzakciós visszahúzás
| SQLSTATE |
Exception |
Leírás |
| 40001 |
OperationalError |
Sorozatolási hiba (holtpont) |
| 40002 |
OperationalError |
Az integritás korlátozásának megsértése visszafordulást okozott |
| 40003 |
OperationalError |
Az utasítás befejezése ismeretlen |
42. osztály – Szintaxishiba vagy hozzáférési szabálysértés
| SQLSTATE |
Exception |
Leírás |
| 42000 |
ProgrammingError |
Szintaxishiba vagy hozzáférés-megsértés |
| 42S01 |
ProgrammingError |
Az alaptábla vagy nézet már létezik |
| 42S02 |
ProgrammingError |
Az alaptábla vagy nézet nem található |
| 42S11 |
ProgrammingError |
Az index már létezik |
| 42S12 |
ProgrammingError |
Az index nem található |
| 42S21 |
ProgrammingError |
Az oszlop már létezik |
| 42S22 |
ProgrammingError |
Az oszlop nem található |
44-es osztály – ELLENŐRZŐ OPCIÓVAL való megsértés
| SQLSTATE |
Exception |
Leírás |
| 44000 |
IntegrityError |
A CHECK OPTION megsértése |
HY osztály – CLI-specifikus állapot
| SQLSTATE |
Exception |
Leírás |
| HY000 |
DatabaseError |
Általános hiba |
| HY001 |
OperationalError |
Memóriafoglalási hiba |
| HY003 |
ProgrammingError |
Érvénytelen alkalmazáspuffer típus |
| HY004 |
ProgrammingError |
Invalid SQL adattípus |
| HY007 |
ProgrammingError |
A kapcsolódó nyilatkozat nincs elkészítve |
| HY008 |
OperationalError |
A műveletet megszakították |
| HY009 |
ProgrammingError |
Érvénytelen null mutató használata |
| HY010 |
ProgrammingError |
Függvényütemezési hiba |
| HY011 |
ProgrammingError |
Az attribútumot most nem lehet beállítani |
| HY012 |
ProgrammingError |
Érvénytelen tranzakciós műveleti kód |
| HY013 |
OperationalError |
Memóriakezelési hiba |
| HY014 |
OperationalError |
A fogantyúk számának határa |
| HY015 |
ProgrammingError |
Nincs kurzornév |
| HY016 |
ProgrammingError |
Nem lehet módosítani egy implementációs sor leírást |
| HY017 |
ProgrammingError |
Automatikusan kijelölt leíró handle érvénytelen használata |
| HY018 |
OperationalError |
A szerver elutasította a törlési kérelmet |
| HY019 |
ProgrammingError |
Darabokban küldött nem-karakter- és nembináris adatok |
| HY020 |
DataError |
Nullérték összekötésének kísérlete |
| HY021 |
ProgrammingError |
Következetlen leíró információk |
| HY024 |
ProgrammingError |
Érvénytelen attribútumérték |
| HY090 |
ProgrammingError |
Érvénytelen sztring vagy puffer hossza |
| HY091 |
ProgrammingError |
Érvénytelen deskriptor mezőazonosító |
| HY092 |
ProgrammingError |
Érvénytelen attribútum/opcióazonosító |
| HY095 |
ProgrammingError |
Függvénytípus a hatótávolságon kívül |
| HY096 |
ProgrammingError |
Érvénytelen információtípus |
| HY097 |
ProgrammingError |
Oszlop típusa a hatótávolságon kívül |
| HY098 |
ProgrammingError |
Távcső típus a hatótávolságon kívül |
| HY099 |
ProgrammingError |
Nullable típus a hatótávolságon kívül |
| HY100 |
ProgrammingError |
Az egyediség beállítástípusa kívül esik a tartományon |
| HY101 |
ProgrammingError |
A pontossági beállítás típusa kívül esik a tartományon |
| HY103 |
ProgrammingError |
Érvénytelen lekérdezési kód |
| HY104 |
ProgrammingError |
Érvénytelen pontosság vagy skála érték |
| HY105 |
ProgrammingError |
Érvénytelen paramétertípus |
| HY106 |
ProgrammingError |
A hatótávolságon kívüli hívó típus |
| HY107 |
ProgrammingError |
Sor értéke a tartományon kívül |
| HY109 |
ProgrammingError |
Érvénytelen kurzorpozíció |
| HY110 |
ProgrammingError |
Érvénytelen driver-teljesítés |
| HY111 |
ProgrammingError |
Érvénytelen könyvjelző érték |
| HYC00 |
NotSupportedError |
A választható funkció nem implementálva |
| HYT00 |
OperationalError |
Az időtúllépés lejárt |
| HYT01 |
OperationalError |
A kapcsolati időkorlát lejárt |
IM osztály – Driver manager hiba
| SQLSTATE |
Exception |
Leírás |
| IM001 |
InterfaceError |
Az illesztőprogram nem támogatja ezt a függvényt |
| IM002 |
InterfaceError |
Adatforrás neve nem található meg |
| IM003 |
InterfaceError |
A megadott illesztőprogramot nem lehetett betölteni |
| IM004 |
InterfaceError |
Driver SQLAllocHandle SQL_HANDLE_ENV hibás |
| IM005 |
InterfaceError |
Driver SQLAllocHandle SQL_HANDLE_DBC hibás |
| IM006 |
InterfaceError |
Driver's SQLSetConnectAttr hibás |
| IM007 |
InterfaceError |
Nem megadva az adatforrás vagy illesztőprogram |
| IM008 |
InterfaceError |
Párbeszéd sikertelen |
| IM009 |
InterfaceError |
Nem lehet betölteni a fordítási DLL-t |
| IM010 |
InterfaceError |
Az adatforrás neve túl hosszú |
| IM011 |
InterfaceError |
A versenyző neve túl hosszú |
| IM012 |
InterfaceError |
DRIVER kulcsszó szintaktishiba |
| IM014 |
InterfaceError |
Érvénytelen DSN |
| IM015 |
InterfaceError |
Sérült fájlforrás |
Gyakori SQL Server hibaszámok
Az SQLSTATE-en túl az SQL Server natív hibaszámokat is tartalmaz zárójelben. Ezek azok a hibák, amelyekkel a legvalószínűbbre fordulsz az alkalmazáskódban. Építsd fel az újrapróbálkozási logikát a 1205-ös hiba (holtpont) és az átmeneti kapcsolati hibák köré (lásd újrapróbálkozás logika).
| Hiba |
Üzenetminta |
Resolution |
| 208 |
Érvénytelen objektumnév |
Ellenőrizd, hogy a tábla vagy nézet létezik-e, és ellenőrizd a séma minősítését. |
| 547 |
Kényszer megsértése |
Egy idegen kulcs vagy csekk korlátozás meghibásodott. |
| 2627 |
Egyedi korlátozás megsértése |
Egy duplikált kulcsértéket adtak be. |
| 2601 |
Egyedi indexsértés |
Az indexben egy duplikált kulcs létezik. |
| 4060 |
Nem lehet adatbázist nyitni |
Az adatbázis nem létezik, vagy a hozzáférés megtagadott. |
| 18456 |
A bejelentkezés sikertelen |
Hitelesítési hiba. Ellenőrizd a képesítéseket. |
| 1205 |
Holtpont áldozata |
A tranzakció vissza lett állítva. Próbálja meg újra a műveletet. |
Tünet-kivétel gyors hivatkozás
Használd ezt a táblázatot, hogy a gyakori tüneteket a kivételtípusokhoz igazítsd, amit el kell kapnod:
| Tünet |
Exception |
Valószínű ok |
| "Bejelentkezés sikertelen a felhasználónál" |
OperationalError |
Rossz hitelesítő adatok vagy a felhasználó nem térképezett az adatbázishoz. |
| "Ügyfél nem tud kapcsolatot teremteni" |
OperationalError |
Szerver elérhetetlen, tűzfal vagy DNS probléma. |
| "Időkorlát lejárt" |
OperationalError |
Lekérdezés vagy kapcsolati időkorlát. Növeld az időkérést vagy optimalizáld a lekérdezést. |
| "Érvénytelen objektumnév" |
ProgrammingError |
Tábla nem létezik, vagy a séma nincs megadva. |
| "Hibás szintaxis" |
ProgrammingError |
SQL szintaxishiba. Tesztlekérdezés SSMS-ben. |
| "Rossz számú paraméter" |
ProgrammingError |
A paraméterszám nem egyezik a helykitöltőkkel. |
| "ELSŐDLEGES KULCS megsértése" |
IntegrityError |
Duplikált kulcs. Használd MERGE vagy ellenőrizd a behelyezés előtt. |
| "KÜLFÖLDI KULCS megsértése" |
IntegrityError |
Hivatkozott sor nem létezik. Először a szülőt helyezd be. |
| "A tranzakció holtpontba került" |
OperationalError (hiba 1205) |
Zár versengés. Újrapróbálkozási logika implementálása. |
| "A string vagy bináris adat levágásra kerülne" |
DataError |
Az érték meghaladja az oszlophosszt. Ellenőrizd az adatokat vagy növelje az oszlop méretét. |
| "Az átalakítás meghiúsult" |
DataError |
Típuseltérés. Használd a megfelelő Python típust az oszlophoz. |
| "Ismeretlen kulcsszó" |
ConnectionStringParseError |
Elírás a kapcsolati karakterlánc kulcsszóban. |
| "Callproc nem támogatott" |
NotSupportedError |
A cursor.execute("EXECUTE ...") használható helyette. |
Bevált gyakorlatok
-
A konkrét kivételeket előbb fogd meg a kivételeket. Sorrend a legspecifikusabbtól (
IntegrityError) a legkevésbé specifikusig (Error).
-
Mindig kezeld az IntegrityError rendszert adatmódosítási műveletekhez. A korlátok megsértése normál működés esetén várhatóak (például ha egy felhasználó megpróbál másolatot létrehozni).
-
Írd be a teljes hibakontextust a hibakereséshez. A kivétel (stabil, SQLSTATE-alapú szöveg) és
ddbc_error (szerveroldali üzenet) megjelenítését driver_error tartalmazza. Mindkettőt naplózni; osztályozni .driver_error
-
Valósítsd meg újrapróbálkozási logikát átmeneti hibák (kapcsolati hibák, holtpontok) esetén. Lásd : Próbálkozás logika.
-
Használj rollback() opciót a kivételkezelőkben a sikertelen tranzakciók tisztítására. Explicit visszafordítás nélkül a kapcsolat meghibásodott tranzakciós állapotban marad.
Kapcsolódó tartalom