Penanganan kesalahan dan kode SQLSTATE untuk mssql-python

Driver mssql-python menentukan hierarki pengecualian standar, pola penanganan kesalahan umum, dan pemetaan kode SQLSTATE untuk SQL Server dan Azure SQL.

Hierarki pengecualian

Driver mssql-python mengikuti hierarki pengecualian DB-API 2.0 (PEP 249):

Exception (builtins)
├── Warning
└── Error
    ├── InterfaceError
    └── DatabaseError
        ├── DataError
        ├── OperationalError
        ├── IntegrityError
        ├── InternalError
        ├── ProgrammingError
        └── NotSupportedError

ConnectionStringParseError (standalone, not part of hierarchy)

Deskripsi pengecualian

Tangkap pengecualian paling spesifik yang sesuai dengan situasi Anda. Misalnya, tangkap IntegrityError untuk pelanggaran batasan pada INSERT/UPDATE operasi, dan ProgrammingError untuk masalah sintaks SQL selama pengembangan. Tangkap kelas dasar Error hanya sebagai penggantian.

Pengecualian Ketika dinaikkan
Warning Peringatan non-fatal dari database.
Error Kelas dasar untuk semua kesalahan database.
InterfaceError Kesalahan yang terkait dengan antarmuka database (driver), bukan database itu sendiri.
DatabaseError Kesalahan yang terkait dengan database.
DataError Kesalahan karena masalah dengan data yang diproses (pembagian nol, nilai di luar jangkauan).
OperationalError Kesalahan yang terkait dengan operasi database (koneksi terputus, alokasi memori, kesalahan transaksi).
IntegrityError Kesalahan saat integritas database terpengaruh (pelanggaran kunci asing, batasan unik).
InternalError Kesalahan database internal (kursor tidak valid, transaksi tidak sinkron).
ProgrammingError Kesalahan pemrograman (kesalahan sintaks, tabel tidak ditemukan, jumlah parameter yang salah).
NotSupportedError Fitur tidak didukung oleh database atau driver.
ConnectionStringParseError Sintaks string koneksi tidak valid atau kata kunci tidak dikenal.

Penanganan kesalahan dasar

Gunakan blok try-except untuk menangani kesalahan database:

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

Akses pengecualian melalui koneksi

Anda dapat menangkap pengecualian melalui instance koneksi:

try:
    cursor.execute("INVALID SQL")
except conn.ProgrammingError as e:
    print(f"Caught via connection: {e}")

Struktur pesan kesalahan

Objek pengecualian mssql-python mengekspos tiga atribut yang berasal dari kelas dasar driverException:

Attribute Source Deskripsi
driver_error Driver Python Teks bahasa Inggris standar yang dipilih oleh SQLSTATE dikembalikan dari ODBC (misalnya, "Communication link failure", , "Invalid authorization specification""Syntax error or access violation"). Stabil di seluruh rilis; aman untuk mencocokkan substring.
ddbc_error Konektivitas Database Langsung (DDBC) Pesan sisi server, biasanya diawali dengan [Microsoft][SQL Server]. Format bukanlah kontrak yang stabil.
message Terdiri f"Driver Error: {driver_error}; DDBC Error: {ddbc_error}". Inilah yang str(exc) kembali. 
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: ...

Nomor kesalahan mesin SQL Server (seperti 208 atau 40501) tidak diekspos sebagai atribut dan tidak disematkan secara andal di salah satu string. Mengklasifikasikan kesalahan berdasarkan subkelas pengecualian ditambah driver_error teks. Untuk pembatasan Azure SQL, lihat Coba lagi logika.

Klasifikasi SQLSTATE

mssql-python menggunakan SQLSTATE yang dikembalikan oleh ODBC untuk memilih subkelas pengecualian Python dan driver_error teks. Pemetaan pengecualian → SQLSTATE lengkap ada exceptions.py di sumber driver. Bagian berikutnya mencantumkan SQLSTATE yang paling sering muncul dengan SQL Server dan Azure SQL.

Kesalahan koneksi

Kegagalan koneksi dari mssql_python.connect() menaikkan mssql_python.OperationalError, sama seperti kegagalan konektivitas lainnya:

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"

Kesalahan string koneksi

Kesalahan penguraian string koneksi memunculkan 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'

Referensi kode SQLSTATE

Kode SQLSTATE adalah kode lima karakter yang mengidentifikasi kondisi kesalahan. Dua karakter pertama menunjukkan kelas, dan tiga karakter terakhir menunjukkan subkelas. Anda jarang perlu memeriksa kode-kode ini secara langsung. Sebagai gantinya, tangkap jenis pengecualian Python yang sesuai (tercantum di kolom "Pengecualian"). Gunakan kode SQLSTATE saat Anda perlu membedakan antara kondisi kesalahan tertentu dalam jenis pengecualian yang sama, misalnya untuk membedakan kebuntuan (40001) dari kegagalan koneksi umum (08S01).

Kelas 00 - Berhasil menyelesaikan

SQLSTATE Pengecualian Deskripsi
00000 None Keberhasilan

Kelas 01 - Peringatan

SQLSTATE Pengecualian Deskripsi
01000 Warning Peringatan umum
01001 Warning Konflik operasi kursor
01002 Warning Putuskan sambungan
01003 DataError Nilai NULL dihilangkan dalam fungsi yang ditetapkan
01004 DataError Data string, pemangkasan kanan
01006 Warning Hak istimewa tidak dicabut
01007 Warning Hak istimewa tidak diberikan
01S00 Warning Atribut string koneksi tidak valid
01S01 Warning Kesalahan dalam baris
01S02 Warning Nilai opsi berubah

Kelas 07 - Kesalahan SQL Dinamis

SQLSTATE Pengecualian Deskripsi
07001 Kesalahan Pemrograman Jumlah parameter yang salah
07002 Kesalahan Pemrograman Bidang COUNT salah
07005 Kesalahan Pemrograman Pernyataan yang disiapkan bukan spesifikasi kursor
07006 Kesalahan Pemrograman Pelanggaran atribut jenis data terbatas
07009 Kesalahan Pemrograman Indeks deskriptor tidak valid
07S01 Kesalahan Pemrograman Penggunaan parameter default tidak valid

Kelas 08 - Pengecualian koneksi

SQLSTATE Pengecualian Deskripsi
08001 Kesalahan Operasional Klien tidak dapat membuat koneksi
08002 Kesalahan Operasional Nama koneksi yang digunakan
08003 Kesalahan Operasional Koneksi tidak ada
08004 Kesalahan Operasional Server menolak koneksi
08007 Kesalahan Operasional Kegagalan koneksi selama transaksi
08S01 Kesalahan Operasional Kegagalan tautan komunikasi

Kelas 21 - Pelanggaran kardinalitas

SQLSTATE Pengecualian Deskripsi
21S01 Kesalahan Pemrograman Daftar nilai yang dimasukkan tidak sesuai dengan daftar kolom
21S02 Kesalahan Pemrograman Tingkat tabel turunan tidak cocok dengan daftar kolom

Kelas 22 - Pengecualian data

SQLSTATE Pengecualian Deskripsi
22001 DataError Data string, pemangkasan kanan
22002 DataError Variabel indikator diperlukan tetapi tidak disediakan
22003 DataError Nilai numerik di luar rentang
22007 DataError Format tanggalwaktu tidak valid
22008 DataError Meluapnya bidang tanggalwaktu
22012 DataError Pembagian dengan nol
22015 DataError Meluapnya bidang interval
22018 DataError Nilai karakter tidak valid untuk spesifikasi cast
22019 DataError Karakter escape tidak valid
22025 DataError Urutan escape tidak valid
22026 DataError Data string, ketidakcocokan panjang

Kelas 23 - Pelanggaran batasan integritas

SQLSTATE Pengecualian Deskripsi
23000 IntegritasKesalahan Pelanggaran batasan integritas (umum)

Kelas 24 - Status kursor tidak valid

SQLSTATE Pengecualian Deskripsi
24000 Kesalahan Internal Status kursor tidak valid

Kelas 25 - Status transaksi tidak valid

SQLSTATE Pengecualian Deskripsi
25000 Kesalahan Operasional Status transaksi tidak valid
25S01 Kesalahan Operasional Status transaksi tidak diketahui
25S02 Kesalahan Operasional Transaksi masih aktif
25S03 Kesalahan Operasional Transaksi dibatalkan

Kelas 28 - Spesifikasi otorisasi yang tidak valid

SQLSTATE Pengecualian Deskripsi
28000 Kesalahan Operasional Spesifikasi otorisasi tidak valid (login gagal)

Kelas 34 - Nama kursor tidak valid

SQLSTATE Pengecualian Deskripsi
34000 Kesalahan Pemrograman Nama kursor tidak valid

Kelas 3C - Nama kursor duplikat

SQLSTATE Pengecualian Deskripsi
3C000 Kesalahan Pemrograman Nama kursor duplikat

Kelas 3D - Nama katalog tidak valid

SQLSTATE Pengecualian Deskripsi
3D000 Kesalahan Pemrograman Nama katalog tidak valid

Kelas 3F - Nama skema tidak valid

SQLSTATE Pengecualian Deskripsi
3F000 Kesalahan Pemrograman Nama skema tidak valid

Kelas 40 - Pengembalian transaksi

SQLSTATE Pengecualian Deskripsi
40001 Kesalahan Operasional Kegagalan serialisasi (kebuntuan)
40002 Kesalahan Operasional Pelanggaran batasan integritas menyebabkan pengembalian
40003 Kesalahan Operasional Penyelesaian pernyataan tidak diketahui

Kelas 42 - Kesalahan sintaks atau pelanggaran aturan akses

SQLSTATE Pengecualian Deskripsi
42000 Kesalahan Pemrograman Kesalahan sintaks atau pelanggaran akses
42S01 Kesalahan Pemrograman Tabel dasar atau tampilan sudah ada
42S02 Kesalahan Pemrograman Tabel dasar atau tampilan tidak ditemukan
42S11 Kesalahan Pemrograman Indeks sudah ada
42S12 Kesalahan Pemrograman Indeks tidak ditemukan
42S21 Kesalahan Pemrograman Kolom sudah ada
42S22 Kesalahan Pemrograman Kolom tidak ditemukan

Kelas 44 - DENGAN OPSI PERIKSA pelanggaran

SQLSTATE Pengecualian Deskripsi
44000 IntegritasKesalahan DENGAN PELANGGARAN OPSI PEMERIKSAAN

Kelas HY - kondisi khusus CLI

SQLSTATE Pengecualian Deskripsi
HY000 DatabaseError Kesalahan umum
HY001 Kesalahan Operasional Kesalahan alokasi memori
HY003 Kesalahan Pemrograman Jenis buffer aplikasi tidak valid
HY004 Kesalahan Pemrograman Tipe data SQL tidak valid
HY007 Kesalahan Pemrograman Pernyataan terkait tidak disiapkan
HY008 Kesalahan Operasional Operasi dibatalkan
HY009 Kesalahan Pemrograman Penggunaan pointer null tidak valid
HY010 Kesalahan Pemrograman Kesalahan urutan fungsi
HY011 Kesalahan Pemrograman Atribut tidak dapat diatur sekarang
HY012 Kesalahan Pemrograman Kode operasi transaksi tidak valid
HY013 Kesalahan Operasional Kesalahan manajemen memori
HY014 Kesalahan Operasional Batas jumlah pegangan terlampaui
HY015 Kesalahan Pemrograman Tidak ada nama kursor yang tersedia
HY016 Kesalahan Pemrograman Tidak dapat mengubah deskriptor baris implementasi
HY017 Kesalahan Pemrograman Penggunaan pegangan deskriptor yang dialokasikan secara otomatis tidak valid
HY018 Kesalahan Operasional Server menolak permintaan pembatalan
HY019 Kesalahan Pemrograman Data non-karakter dan non-biner dikirim dalam beberapa bagian
HY020 DataError Mencoba menggabungkan nilai null
HY021 Kesalahan Pemrograman Informasi deskriptor yang tidak konsisten
HY024 Kesalahan Pemrograman Nilai atribut tidak valid
HY090 Kesalahan Pemrograman String atau panjang buffer tidak valid
HY091 Kesalahan Pemrograman Pengidentifikasi bidang deskriptor tidak valid
HY092 Kesalahan Pemrograman Pengidentifikasi atribut/opsi tidak valid
HY095 Kesalahan Pemrograman Jenis fungsi di luar jangkauan
HY096 Kesalahan Pemrograman Jenis informasi tidak valid
HY097 Kesalahan Pemrograman Jenis kolom di luar jangkauan
HY098 Kesalahan Pemrograman Jenis ruang lingkup di luar jangkauan
HY099 Kesalahan Pemrograman Jenis nullable di luar jangkauan
HY100 Kesalahan Pemrograman Jenis opsi keunikan di luar rentang
HY101 Kesalahan Pemrograman Jenis opsi akurasi di luar rentang
HY103 Kesalahan Pemrograman Kode pengambilan tidak valid
HY104 Kesalahan Pemrograman Presisi atau nilai skala tidak valid
HY105 Kesalahan Pemrograman Jenis parameter tidak valid
HY106 Kesalahan Pemrograman Ambil jenis di luar jangkauan
HY107 Kesalahan Pemrograman Nilai baris di luar jangkauan
HY109 Kesalahan Pemrograman Posisi kursor tidak valid
HY110 Kesalahan Pemrograman Penyelesaian driver tidak valid
HY111 Kesalahan Pemrograman Nilai bookmark tidak valid
HYC00 NotSupportedError Fitur opsional tidak diimplementasikan
HYT00 Kesalahan Operasional Waktu habis kedaluwarsa
HYT01 Kesalahan Operasional Waktu tunggu koneksi habis

Kelas IM - Kesalahan pengelola driver

SQLSTATE Pengecualian Deskripsi
IM001 Kesalahan Antarmuka Driver tidak mendukung fungsi ini
IM002 Kesalahan Antarmuka Nama sumber data tidak ditemukan
IM003 Kesalahan Antarmuka Pengandar yang ditentukan tidak dapat dimuat
IM004 Kesalahan Antarmuka SQLAllocHandle driver pada SQL_HANDLE_ENV gagal
IM005 Kesalahan Antarmuka SQLAllocHandle driver pada SQL_HANDLE_DBC gagal
IM006 Kesalahan Antarmuka SQLSetConnectAttr driver gagal
IM007 Kesalahan Antarmuka Tidak ada sumber data atau driver yang ditentukan
IM008 Kesalahan Antarmuka Dialog gagal
IM009 Kesalahan Antarmuka Tidak dapat memuat DLL terjemahan
IM010 Kesalahan Antarmuka Nama sumber data terlalu panjang
IM011 Kesalahan Antarmuka Nama driver terlalu panjang
IM012 Kesalahan Antarmuka Kesalahan sintaks kata kunci DRIVER
IM014 Kesalahan Antarmuka DSN tidak valid
IM015 Kesalahan Antarmuka Sumber data file yang rusak

Nomor kesalahan SQL Server umum

Di luar SQLSTATE, SQL Server menyediakan nomor kesalahan asli dalam tanda kurung. Ini adalah kesalahan yang paling mungkin Anda temui dalam kode aplikasi. Bangun logika coba lagi di sekitar kesalahan 1205 (kebuntuan) dan kesalahan koneksi sementara (lihat Logika coba lagi).

Kesalahan Pola pesan Resolution
208 Nama objek tidak valid Verifikasi bahwa tabel atau tampilan ada dan periksa kualifikasi skema.
547 Pelanggaran batasan Kunci asing atau batasan pemeriksaan gagal.
2627 Pelanggaran batasan unik Nilai kunci duplikat dimasukkan.
2601 Pelanggaran indeks unik Kunci duplikat ada di indeks.
4060 Tidak dapat membuka database Database tidak ada atau akses ditolak.
18456 Gagal masuk Kegagalan autentikasi. Periksa kredensial.
1205 Korban kebuntuan Transaksi digulung balik. Coba lagi operasi.

Referensi cepat gejala-ke-pengecualian

Gunakan tabel ini untuk memetakan gejala umum ke jenis pengecualian yang harus Anda tangkap:

Gejala Pengecualian Kemungkinan penyebabnya
"Login gagal untuk pengguna" OperationalError Kredensial yang salah atau pengguna tidak dipetakan ke database.
"Klien tidak dapat membuat koneksi" OperationalError Server tidak dapat dijangkau, firewall, atau masalah DNS.
"Batas waktu kedaluwarsa" OperationalError Batas waktu kueri atau koneksi. Tingkatkan batas waktu atau optimalkan kueri.
"Nama objek tidak valid" ProgrammingError Tabel tidak ada atau skema tidak ditentukan.
"Sintaks salah" ProgrammingError Kesalahan sintaks SQL. Kueri pengujian di SSMS.
"Jumlah parameter yang salah" ProgrammingError Jumlah parameter tidak cocok dengan placeholder.
"Pelanggaran KUNCI UTAMA" IntegrityError Kunci duplikat. Gunakan MERGE atau periksa sebelum memasukkan.
"Pelanggaran KUNCI ASING" IntegrityError Baris yang direferensikan tidak ada. Masukkan induk terlebih dahulu.
"Transaksi menemui jalan buntu" OperationalError (kesalahan 1205) Kunci pertentangan. Menerapkan logika pengulangan.
"Data string atau biner akan dipotong" DataError Nilai melebihi panjang kolom. Periksa data atau tingkatkan ukuran kolom.
"Konversi gagal" DataError Jenis data tidak cocok. Gunakan jenis Python yang benar untuk kolom.
"Kata kunci tidak dikenal" ConnectionStringParseError Typo dalam kata kunci string koneksi.
"Callproc tidak didukung" NotSupportedError Gunakan cursor.execute("EXECUTE ...") sebagai gantinya.

Praktik terbaik

  • Tangkap pengecualian tertentu sebelum pengecualian generik. Urutkan dari yang paling spesifik (IntegrityError) hingga yang paling tidak spesifik (Error).
  • Selalu tangani IntegrityError untuk operasi modifikasi data. Pelanggaran batasan diharapkan dalam operasi normal (misalnya, pengguna mencoba membuat nama pengguna duplikat).
  • Catat konteks kesalahan lengkap untuk pemecahan masalah. Pengecualian mengekspos driver_error (teks stabil, turunan SQLSTATE) dan ddbc_error (pesan sisi server). Catat keduanya; mengklasifikasikan pada driver_error.
  • Terapkan logika coba lagi untuk kesalahan sementara (kegagalan koneksi, kebuntuan). Lihat Logika coba lagi.
  • Gunakan rollback() di penanganan pengecualian untuk membersihkan transaksi yang gagal. Tanpa pengembalian eksplisit, koneksi tetap dalam status transaksi gagal.

Konten terkait

  • Last updated on