Memecahkan masalah pada Microsoft OLE DB Driver for SQL Server

Berlaku untuk:SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics SQL database di Microsoft Fabric

Gunakan artikel ini untuk mengidentifikasi tahap kegagalan operasi OLE DB, pilih pemeriksaan berikutnya, dan temukan instruksi pemecahan masalah yang rinci. Panduan ini menggunakan penyedia saat ini, MSOLEDBSQL19. Untuk cacat spesifik rilis dan perubahan upgrade, lihat Masalah yang diketahui dan perbedaan versi utama.

Identifikasi gejalanya

Tangkap deskripsi kesalahan lengkap dan semua catatan kesalahan yang tersedia sebelum mengubah pengaturan. Tingkat atas HRESULT, seperti DB_E_ERRORSOCCURRED, tidak mengidentifikasi penyebabnya sendiri. Catat apakah kegagalan terjadi saat memuat provider, membuka koneksi, menjalankan perintah, mengambil data, atau melakukan transaksi.

Gejala	Mulai di sini
Penyedia tidak dapat ditemukan, atau kelas tidak terdaftar.	Registrasi dan arsitektur penyedia
Login gagal, akses ditolak, atau autentikasi terintegrasi gagal.	Kegagalan login dan autentikasi
Rantai sertifikat tidak dipercaya, atau nama sertifikat tidak cocok.	Kegagalan sertifikat TLS
Server atau instance tidak dapat ditemukan, atau koneksi ditolak.	Kegagalan penemuan jaringan dan instance
Parameter gagal, nilainya terpotong, atau data tidak dapat dikonversi.	Kesalahan parameter dan konversi data
Koneksi putus, pemulihan gagal, atau waktu tunggu berakhir.	Kehilangan koneksi dan timeout
Detail kesalahan hilang, atau Anda membutuhkan pelacakan untuk dukungan.	Diagnostik dan pelacakan

Untuk kegagalan koneksi, bandingkan aplikasi dengan uji koneksi Universal Data Link (UDL). Gunakan komputer, penyedia, arsitektur proses, identitas autentikasi, server, basis data, dan pengaturan enkripsi yang sama. Pengujian yang berhasil dengan penyedia atau identitas berbeda tidak menunjukkan bahwa konfigurasi aplikasi berfungsi.

Registrasi dan arsitektur penyedia

Kesalahan seperti Provider tidak dapat ditemukan atau REGDB_E_CLASSNOTREG (0x80040154, Kelas tidak terdaftar) menunjukkan pemuatan provider sebelum autentikasi SQL Server.

Periksa penyedia yang diminta oleh aplikasi. MSOLEDBSQL19 dan MSOLEDBSQL mengidentifikasi berbagai versi utama. Menginstal driver saat ini tidak mengubah pilihan penyedia aplikasi. Ikuti langkah-langkah migrasi jika aplikasi masih meminta penyedia lain.
Periksa arsitektur proses yang menjadi host aplikasi. Aplikasi 32-bit membutuhkan penyedia 32-bit, bahkan di Windows 64-bit. Untuk layanan atau pekerjaan terjadwal, periksa executable dan akun yang digunakan oleh host tersebut, bukan hanya lingkungan pengembangan Anda.
Instal atau perbaiki driver dengan installer yang didukung di komputer yang menjalankan aplikasi tersebut. Installer x64 mencakup biner driver 64-bit dan 32-bit. Periksa ketergantungan yang diperlukan di Install the OLE DB Driver and System requirements. Jangan menyalin pustaka driver dari komputer lain sebagai pengganti instalasi.
Ulangi uji UDL dengan arsitektur dan penyedia yang cocok. Jika berfungsi tetapi aplikasi masih tidak dapat memuat provider, bandingkan pemilihan provider efektif aplikasi dan arsitektur host dengan pengujian.

Jika kesalahan secara spesifik menyebutkan adal.dll, periksa masalah pustaka autentikasi yang sudah diketahui daripada memperlakukannya sebagai penyedia SQL Server yang hilang.

Membedakan penolakan login server dari kegagalan memperoleh kredensial atau membangun koneksi terenkripsi. Baca teks lengkap dari kesalahan, termasuk kesalahan penyedia yang bertingkat.

Untuk kesalahan SQL Server 18456, minta administrator database memeriksa entri log kesalahan server dan status yang sesuai. Periksa mode autentikasi, status login, permintaan database, dan akses database menggunakan MSSQLSERVER_18456. Jangan berasumsi setiap penolakan login berarti kata sandi yang salah.
Untuk autentikasi terintegrasi, pastikan identitas yang digunakan aplikasi saat berjalan. Akun layanan atau akun tugas terjadwal dapat berbeda dari pengguna yang berhasil menguji koneksi. Jika pesan berisi Tidak dapat menghasilkan konteks SSPI, ikuti pemecahan masalah Security Support Provider Interface (SSPI) dan dukungan Service Principal Name (SPN).
Untuk Microsoft Entra ID, periksa bahwa metode autentikasi yang dipilih sesuai dengan lingkungan eksekusi aplikasi dan bahwa identitasnya memiliki akses ke database target. Tinjau pengaturan khusus metode dan pembatasan token akses di Use Microsoft Entra ID. Jangan menggabungkan token akses dengan properti autentikasi atau kredensial yang bertentangan.
Bandingkan pengaturan efektif dengan tabel kata kunci string koneksi yang benar. IDBInitialize::Initialize, IDataInitialize::GetDataSource, dan ActiveX Data Objects (ADO) menggunakan tabel kata kunci yang berbeda. Periksa tabel untuk antarmuka yang digunakan aplikasi Anda.

Teks Nama prinsipal target salah dapat muncul dalam konteks yang berbeda. Jika disertai Cannot generate SSPI context, selidiki autentikasi Windows dan SPN. Jika kesalahan menunjukkan sertifikat atau proses jabat tangan enkripsi, gunakan bagian berikutnya.

Kegagalan sertifikat TLS

Kesalahan Transport Layer Security (TLS) dapat terjadi sebelum login mencapai SQL Server. Driver saat ini mengaktifkan enkripsi wajib secara default, sehingga peningkatan dapat mengekspos masalah kepercayaan sertifikat atau nama yang tidak terdeteksi oleh konfigurasi koneksi lama.

Untuk Rantai sertifikat diterbitkan oleh otoritas yang tidak dipercaya, periksa sertifikat yang disajikan SQL Server dan rantai sertifikat penerbit yang dipercaya oleh komputer klien. Konfigurasikan sertifikat server yang valid dan instal sertifikat root dan intermediate yang terpercaya yang diperlukan melalui proses manajemen sertifikat organisasi Anda.
Untuk ketidakcocokan nama sertifikat, bandingkan nama server atau pendengar yang digunakan aplikasi dengan nama-nama dalam sertifikat. Gunakan sertifikat yang mencakup nama koneksi yang dimaksud. Jika aplikasi sengaja menggunakan nama koneksi yang berbeda, tinjau properti HostNameInCertificate yang didokumentasikan sebelum mengonfigurasi nama sertifikat yang diharapkan.
Periksa pengaturan enkripsi dan validasi yang efektif, termasuk pengaturan registry. Tinjau tabel enkripsi dan validasi sertifikat untuk prioritas dan Strict perilaku. Dalam mode Strict, driver memvalidasi sertifikat terlepas dari pengaturan trust-server-certificate.
Jika kegagalan dimulai selama migrasi, periksa pemecahan masalah versi utama, termasuk tipe nilai properti enkripsi dan pembatasan penggunaan ServerCertificate mode luar Strict .

Gunakan Persyaratan sertifikat untuk SQL Server dan Pemecahan masalah rantai sertifikat yang tidak tepercaya untuk pemeriksaan terperinci. Aktifkan enkripsi dan validasi sertifikat di produksi. Menonaktifkan salah satu tidak memperbaiki masalah penerapan sertifikat.

Kegagalan penemuan jaringan dan instance

Untuk server tidak ditemukan, kesalahan saat menemukan server/instance yang ditentukan, atau kesalahan koneksi ditolak, identifikasi titik akhir yang coba dijangkau oleh aplikasi.

Verifikasi nama server, nama instance, dan port listening yang dikonfigurasi dengan administrator database. Konfirmasi bahwa layanan basis data berjalan dan protokol serta pendengar yang dimaksud diaktifkan. Jangan berasumsi bahwa setiap instance menggunakan port 1433.
Untuk koneksi Transmission Control Protocol (TCP) jarak jauh, uji endpoint yang sudah diketahui menggunakan format nama server milik driver tcp:<server>,<port>. Pertahankan pengaturan autentikasi, basis data, dan enkripsi yang sama. Lihat Kata kunci string koneksi untuk kata kunci server yang berlaku untuk antarmuka Anda.
Jika host dan port eksplisit berfungsi tetapi instans bernama tidak, selidiki SQL Server Browser dan penemuan instans. Periksa layanan Browser dan jalur port User Datagram Protocol (UDP) 1434 di mana penemuan browser digunakan.
Jika endpoint eksplisit juga gagal, periksa resolusi Domain Name System (DNS), routing, dan akses firewall ke port listening aktual dari host aplikasi. Ikuti petunjuk untuk mengatasi kesalahan koneksi terkait jaringan atau khusus instans alih-alih mengubah beberapa pengaturan koneksi sekaligus.

Untuk listener grup ketersediaan, lihat juga dukungan ketersediaan tinggi dan pemulihan bencana. Untuk LocalDB, gunakan dukungan LocalDB untuk memeriksa instance lokal dan konteks pengguna daripada menerapkan langkah penemuan TCP jarak jauh.

Kesalahan parameter dan konversi data

Jika koneksi berhasil dibuka tetapi eksekusi perintah atau pengambilan data gagal, perkecil kasus reproduksi hingga hanya mencakup perintah dan nilai yang gagal. Pertahankan tipe data asli, panjang, status null, dan pengkodean karakter saat mengganti data sensitif.

Bandingkan setiap ? penanda parameter dengan ordinal pengikat, arah, dan metadata. Saat Anda menggunakan ICommandWithParameters::SetParameterInfo, cocokkan tipe sumber SQL dengan perintah atau prosedur tersimpan. Jangan berasumsi metadata parameter selalu diturunkan secara otomatis. Tinjau parameter perintah untuk mengetahui pembatasan derivasi dan perilaku parameter output.
Periksa status pengikatan pengakses serta status dan panjang setiap nilai yang dikembalikan, bukan hanya status keseluruhan HRESULT. Untuk kegagalan pengaturan properti, periksa dwStatus setiap properti. Hasil pengembalian dengan keberhasilan parsial seperti DB_S_ERRORSOCCURRED dapat memerlukan pemeriksaan larik status meskipun tidak ada objek kesalahan yang tersedia. Lihat Kode Pengembalian.
Untuk konversi atau pemotongan, bandingkan tipe dan ukuran buffer konsumen dengan metadata kolom atau parameter yang sebenarnya. Periksa presisi dan skala untuk nilai numerik, rentang yang valid dan pecahan detik untuk nilai tanggal/waktu, serta panjang byte untuk buffer karakter. Selidikilah DBSTATUS_E_CANTCONVERTVALUE, dan jangan perlakukan DBSTATUS_S_TRUNCATED sebagai nilai penuh. Gunakan pemetaan tipe data, pengambilan baris, serta konversi tanggal dan waktu untuk aturan yang berlaku.
Jika parameter output terikat tampak hilang, habiskan baris yang dikembalikan sebelum membacanya. Ikuti Use IMultipleResults untuk memproses beberapa set hasil. Untuk parameter output streaming, konsumsi atau lepaskan stream yang tertunda sebelum meminta hasil berikutnya, seperti dijelaskan dalam Dukungan streaming untuk parameter output.

Untuk pemetaan khusus ADO, tinjau Gunakan ADO dengan Driver OLE DB dan pembatasan otentikasi pada DataTypeCompatibilityGunakan Microsoft Entra ID. Jangan tambahkan pengaturan kompatibilitas tanpa memeriksa keduanya.

Untuk string sempit yang rusak di kolom sql_variant setelah upgrade driver, tinjau isu SSVARIANT yang sudah diketahui dan prosedur pemulihan sebelum memodifikasi data yang tersimpan.

Kehilangan koneksi dan waktu habis

Catat kapan koneksi terakhir berfungsi, operasi mana yang gagal, dan berapa lama operasi tersebut berjalan. Bedakan kasus-kasus ini sebelum mengubah pengaturan percobaan ulang atau timeout.

Tahap kegagalan	Pemeriksaan dan panduan rinci
Membuka koneksi.	Periksa dulu kesalahan provider, jaringan, autentikasi, dan TLS. Periksa `DBPROP_INIT_TIMEOUT` yang berlaku atau kata kunci koneksi yang sesuai. Lihat Pemecahan masalah batas waktu koneksi.
Menjalankan perintah.	Periksa `DBPROP_COMMANDTIMEOUT` atau pengaturan batas waktu perintah aplikasi. Selidiki pemblokiran dan performa kueri dengan Pemecahan masalah batas waktu kueri. Meningkatkan batas waktu koneksi tidak akan mengubah batas waktu perintah.
Menggunakan kembali koneksi yang tidak aktif.	Periksa kondisi pemulihan, pengaturan coba ulang, dan kesalahan yang diharapkan dalam ketahanan koneksi Idle. Pemulihan dapat gagal ketika batas waktu perintah berakhir sebelum penyambungan ulang selesai.
Kehilangan koneksi saat eksekusi atau komitmen.	Korelasikan kejadian klien dan server untuk memeriksa gangguan jaringan, restart server, atau failover. Tentukan hasil operasi sebelum memutuskan apakah aman untuk mencoba ulang.

Ketahanan koneksi idle tidak menyediakan percobaan ulang koneksi awal atau pemutaran ulang otomatis atas perintah dan transaksi sembarangan. Untuk kegagalan transien yang terkonfirmasi, gunakan percobaan ulang aplikasi terbatas dengan jeda, dan catat setiap percobaan. Jangan berulang kali mengulangi percobaan untuk kesalahan pemuatan penyedia, kredensial yang ditolak, atau kegagalan validasi sertifikat tanpa memperbaiki penyebabnya.

Caution

Jika koneksi terputus saat penulisan atau komit, klien mungkin tidak tahu apakah SQL Server telah melakukan komit transaksi. Jangan memutar ulang operasi itu secara membabi buta. Periksa hasilnya atau gunakan desain aplikasi yang mencegah efek duplikat sebelum mencoba ulang.

Diagnostik dan pelacakan

Kumpulkan data diagnostik saat kegagalan terjadi, sebelum pemanggilan ke penyedia lain yang tidak terkait menggantikan informasi kesalahan.

Catat operasi yang gagal, stempel waktu dan zona waktu, waktu yang berlalu, dan HRESULT. Untuk konsumen OLE DB asli, ambil semua catatan yang tersedia melalui IErrorInfo dan IErrorRecords, bukan hanya deskripsi pertama. Sertakan SQLSTATE dan nomor kesalahan asli SQL Server jika tersedia melalui ISQLErrorInfo. Lihat Ambil informasi kesalahan dan detail kesalahan SQL Server. Untuk ADO, tangkap koleksi koneksi Errors .
Kumpulkan status per properti, per binding, dan per nilai untuk metode yang melaporkan kesalahan dengan cara tersebut. Tidak adanya objek error tidak berarti hasil sukses parsial aman untuk diabaikan.
Korelasikan kegagalan klien dengan log kesalahan server atau Extended Events. Jika tersedia, catat ClientConnectionID dan ActivityID. Kegagalan sebelum pra-login dapat terjadi tanpa pengenal koneksi klien.
Jika catatan kesalahan tidak cukup, gunakan informasi diagnostik Access di log Extended Events untuk pelacakan driver dan pengaturan korelasi. Kumpulkan jejak terbatas di sekitar reproduksi dan berhenti menelusuri setelahnya.

Saat Anda melakukan eskalasi, sertakan versi driver, penyedia yang diminta, arsitektur aplikasi dan proses, versi server, metode autentikasi, pengaturan koneksi efektif, tahap kegagalan, catatan kesalahan, dan reproduksi minimal. Nyatakan apakah tes UDL yang cocok berhasil dan apakah masalah ini memengaruhi satu host atau beberapa host.

Hapus kata sandi, token akses, dan rahasia lain dari pengaturan koneksi dan log. Tinjau jejak untuk teks kueri dan data sensitif, simpan dengan akses terbatas, dan bagikan hanya melalui saluran dukungan yang disetujui.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-09-23