Memecahkan masalah driver go-mssqldb

Artikel ini memberikan solusi untuk kesalahan umum dan masalah konektivitas dengan go-mssqldb driver.

Mulailah dengan pemeriksaan paling sederhana

Sebelum Anda mengaktifkan pengelogan verbose atau mengubah pengaturan kumpulan, kerjakan daftar berikut:

  1. Verifikasi jangkauan dasar: nama server, port, aturan firewall, dan apakah SQL Server atau Azure SQL menerima koneksi.
  2. Periksa masukan autentikasi: nama driver, nama pengguna, sandi, format domain, atau konfigurasi fedauth.
  3. Verifikasi pengaturan TLS: encrypt, jalur sertifikat, hostnameincertificate, dan apakah TrustServerCertificate sesuai untuk lingkungan.
  4. Hanya setelah konfigurasi koneksi sudah benar, barulah selidiki kehabisan kapasitas pool koneksi, koneksi basi, logika percobaan ulang, serta diagnostik kueri yang lambat atau terblokir.

Gunakan bagian awal artikel ini jika penyiapan koneksi gagal. Gunakan bagian-bagian berikut hanya setelah koneksi setidaknya kadang-kadang berhasil lalu gagal saat berada di bawah beban, setelah tidak aktif selama beberapa waktu, atau selama failover.

Kesalahan koneksi

Bagian berikut mencakup pesan kesalahan umum terkait koneksi dan solusinya.

Tidak dapat membuka koneksi TCP

Pesan kesalahan:unable to open tcp connection with host 'localhost:1433': dial tcp 127.0.0.1:1433: connectex: No connection could be made because the target machine actively refused it.

Penyebab dan solusi:

  • SQL Server tidak berjalan. Mulai layanan SQL Server.
  • TCP/IP tidak diaktifkan. Buka Pengelola Konfigurasi SQL Server dan aktifkan TCP/IP di bawahProtokol> SQL Server.
  • Port yang salah. Verifikasi port di Pengelola Konfigurasi SQL Server atau gunakan SQL Server Browser untuk instans bernama.
  • Firewall memblokir port. Tambahkan aturan masuk untuk port 1433 (atau port yang dikonfigurasi).

Gagal masuk untuk pengguna

Pesan kesalahan:mssql: login error: Login failed for user '<user>'.

Penyebab dan solusi:

  • Nama pengguna atau kata sandi salah. Verifikasi kredensial.
  • Autentikasi SQL Server dinonaktifkan. Aktifkan mode SQL Server dan Windows Authentication di properti server.
  • Login tidak ada. Buat login di SQL Server.
  • Login tidak memiliki akses ke database target. Berikan akses database dengan CREATE USER.

Kesalahan validasi sertifikat

Pesan kesalahan:TLS Handshake failed: x509: certificate signed by unknown authority

Penyebab dan solusi:

  • Server menggunakan sertifikat yang ditandatangani sendiri. Berikan jalur sertifikat melalui parameter certificate atau serverCertificate, atau tetapkan TrustServerCertificate=true hanya untuk pengembangan.
  • Sertifikat CA tidak ada di penyimpanan kepercayaan sistem. Tambahkan sertifikat CA ke penyimpanan kepercayaan OS atau tentukan dengan certificate parameter.
  • Nama host tidak cocok. Gunakan hostnameincertificate untuk menentukan nama yang diharapkan dalam sertifikat.

Untuk informasi selengkapnya, lihat Enkripsi dan sertifikat.

Waktu tunggu koneksi habis

Pesan kesalahan:unable to open tcp connection with host '<server>:1433': dial tcp: i/o timeout

Penyebab dan solusi:

  • Masalah konektivitas jaringan. Pastikan Anda dapat menjangkau server dengan menggunakan telnet <server> 1433 atau Test-NetConnection -ComputerName <server> -Port 1433.
  • Kegagalan resolusi DNS. Verifikasi nama host diselesaikan dengan benar.
  • Tingkatkan dial timeout atau connection timeout dalam string koneksi.

Kesalahan autentikasi

Bagian berikut mencakup pesan kesalahan autentikasi.

Kegagalan autentikasi NTLM

Pesan kesalahan:NTLM authentication failed

Penyebab dan solusi:

  • Format domain tidak valid. Gunakan DOMAIN\user dalam user id parameter. Dalam format URL, kodekan garis miring terbalik sebagai %5C.
  • Kata sandi salah. Verifikasi kata sandi domain.

Kegagalan autentikasi Kerberos

Pesan kesalahan:krb5: cannot resolve KDC for realm

Penyebab dan solusi:

  • Hilang atau salah konfigurasi /etc/krb5.conf. Pastikan bagian tersebut [realms] berisi alamat KDC yang benar untuk domain Anda.
  • Tidak ada tiket yang valid. Jalankan klist untuk memeriksa apakah ada tiket yang valid, atau jalankan kinit untuk mendapatkan tiket.
  • File keytab tidak ditemukan. Verifikasi jalur dalam krb5-keytabfile parameter.

Untuk informasi selengkapnya, lihat SQL Server dan Windows authentication.

Kegagalan autentikasi Microsoft Entra ID

Pesan kesalahan: clientCredentialFromCert: error reading certificate: ... atau DefaultAzureCredential: failed to acquire a token

Penyebab dan solusi:

  • ID klien, ID penyewa, atau rahasia klien salah. Verifikasi nilai dalam string koneksi atau variabel lingkungan.
  • Identitas terkelola tidak dikonfigurasi pada host. Verifikasi identitas di portal Azure.
  • Impor paket azuread hilang. Impor github.com/microsoft/go-mssqldb/azuread dan gunakan nama driver azuresql.

Untuk informasi selengkapnya, lihat Autentikasi ID Microsoft Entra.

Login gagal untuk pengguna '' (nama pengguna kosong)

Pesan kesalahan:mssql: login error: Login failed for user ''.

Penyebab: Anda menggunakan sql.Open("sqlserver", ...) dengan parameter fedauth. Otentikasi Entra ID memerlukan nama driver azuresql yang didaftarkan oleh paket azuread. Dengan driver standar sqlserver , fedauth parameter diabaikan dan driver mencoba autentikasi SQL tanpa nama pengguna.

Solusi: Impor azuread paket dan gunakan azuresql nama driver:

import _ "github.com/microsoft/go-mssqldb/azuread"

db, err := sql.Open("azuresql",
    "sqlserver://<server>.database.windows.net?database=AdventureWorks2025&fedauth=ActiveDirectoryDefault&encrypt=true&TrustServerCertificate=false")
if err != nil {
    panic(err)
}

Untuk informasi selengkapnya, lihat Autentikasi ID Microsoft Entra.

Kesalahan kueri

Bagian berikut mencakup pesan kesalahan eksekusi kueri.

LastInsertId tidak didukung

Pesan kesalahan:LastInsertId is not supported. Please use the OUTPUT clause or add 'select ID = convert(bigint, SCOPE_IDENTITY())' to the end of your query.

Solusi: Driver go-mssqldb tidak mendukung LastInsertId(). Gunakan OUTPUT klausa atau kueri SCOPE_IDENTITY() secara terpisah.

Tabel sementara tidak ditemukan

Pesan kesalahan:mssql: Invalid object name '#TempTable'.

Penyebab: Tabel sementara dibuat untuk setiap koneksi. Jika Anda membuat tabel sementara dalam satu panggilan dan mengkuerinya di panggilan lain, mereka mungkin menggunakan koneksi yang berbeda dari kumpulan.

Solusi: Gunakan db.Conn(ctx) untuk mengikat ke satu koneksi, atau bungkus operasi dalam transaksi.

Untuk informasi selengkapnya, lihat Prosedur tersimpan.

Kesalahan Azure SQL

Bagian berikut mencakup kesalahan khusus untuk Azure SQL Database.

Nomor kesalahan koneksi sementara

Gunakan daftar bersama berikut sebagai referensi untuk kesalahan pembuatan koneksi sementara dan kegagalan transportasi jalur permintaan yang memenuhi syarat untuk percobaan ulang terbatas:

Kesalahan berikut bersifat sementara ketika terjadi selama pembentukan koneksi atau saat mengirim permintaan ke server. Coba lagi setelah penundaan singkat yang dibatasi. Kesalahan yang bertahan melewati beberapa percobaan ulang biasanya menunjukkan masalah konfigurasi (server yang salah, izin yang hilang, kuota habis) yang coba lagi tidak akan diperbaiki.

Kesalahan Message Troubleshooting
64 A connection was successfully established with the server, but then an error occurred during the login process. (provider: TCP Provider, error: 0 - The specified network name is no longer available.) Koneksi TCP terputus di tengah proses handshake. Bukan kegagalan kredensial. Jika berlanjut, periksa ketidakstabilan jaringan sisi klien atau perangkat perantara yang menghilangkan koneksi yang setengah dibuat.
233 The client was unable to establish a connection because of an error during connection initialization process before login. Transportasi pra-login atau kegagalan TLS. Server biasanya mengembalikannya ketika tidak dapat menerima koneksi (kelelahan sumber daya, koneksi maks tercapai, atau klien yang tidak didukung). Bukan kegagalan kredensial. Verifikasi kesehatan server, lalu periksa batas waktu masuk klien, pengaturan TLS, dan kompatibilitas versi TLS klien/server.
4060 Cannot open database "%.*ls" requested by the login. The login failed. Login mengautentikasi tetapi tidak dapat membuka database yang diminta. Penyebab sementara antara lain database sedang dalam transisi (failover, pemulihan, penskalaan) atau dijeda secara otomatis. Penyebab yang bersifat permanen (database tidak ada, login tidak memiliki akses) tidak akan teratasi dengan mencoba lagi; periksa nama database, pemetaan login, dan status database.
4221 Login to read-secondary failed due to long wait on 'HADR_DATABASE_WAIT_FOR_TRANSITION_TO_VERSIONING'. Replika tidak tersedia untuk masuk karena versi baris hilang untuk transaksi yang sedang dalam penerbangan saat replika didaur ulang. Batalkan atau komitkan transaksi yang aktif di server primer untuk menyelesaikan masalah. Kurangi risikonya dengan menghindari transaksi penulisan yang berlangsung lama pada node utama.
10053 A transport-level error has occurred when sending the request to the server. (provider: TCP Provider, error: 0 - An established connection was aborted by the software in your host machine.) Pihak lokal memutuskan koneksi. Periksa kesehatan jaringan sisi klien dan firewall lokal atau klien VPN apa pun.
10054 A transport-level error has occurred when sending the request to the server. (provider: TCP Provider, error: 0 - An existing connection was forcibly closed by the remote host.) Sisi jarak jauh mengirimkan reset TCP. Penyebab umum: proses peer mengalami kegagalan, firewall mengirim reset, atau gateway Azure SQL menutup koneksi yang tidak aktif. Untuk pola reset saat idle, aktifkan TCP keepalive pada klien atau perpendek waktu tunggu idle pada pool koneksi.
10928 Resource ID: %d. The %s limit for the database is %d and has been reached. See 'http://go.microsoft.com/fwlink/?LinkId=267637' for assistance. Database melebihi batas tata kelola sumber daya Azure SQL. ID Sumber Daya 1 menunjukkan batas pekerja; ID Sumber Daya 2 menunjukkan batas sesi. Identifikasi jenis batas berdasarkan pesan, lalu kurangi tingkat konkurensi, tingkatkan kapasitas database, atau persingkat operasi berjalan lama yang menggunakan sumber daya tersebut terlalu lama.
10929 Resource ID: %d. The %s minimum guarantee is %d, maximum limit is %d, and the current usage for the database is %d. However, the server is currently too busy to support requests greater than %d for this database. Database telah melampaui batas jaminan minimumnya, dan server yang mendasarinya sedang mengalami pembatasan. Percobaan ulang biasanya berhasil saat beban pada node tetangga menurun. Kejadian berkelanjutan menunjukkan Bahwa Anda memerlukan tingkat layanan yang lebih tinggi atau lingkungan yang kurang bising.
40020,40143,40166,40540 Dilaporkan pada slot Error code %d pada kesalahan 40197 selama failover. Sub-kode yang disematkan dalam pesan failover 40197 bahwa beberapa jalur muncul sebagai nomor kesalahan tingkat atas. Perlakukan mereka sama seperti 40197.
40197 The service has encountered an error processing your request. Please try again. Error code %d. Peningkatan perangkat lunak, kegagalan perangkat keras, atau peristiwa failover lainnya di Azure SQL. Penyambungan ulang akan mengarahkan Anda ke replika yang sehat. Kode kesalahan yang disematkan mengidentifikasi jenis failover. Jika kesalahan berlanjut, ambil ID pelacakan sesi dan hubungi dukungan.
40501 The service is currently busy. Retry the request after 10 seconds. Incident ID: %ls. Code: %d. Pelambatan mesin Azure SQL. Batas minimum yang direkomendasikan adalah backoff 10 detik. Throttling yang berkelanjutan menunjukkan bahwa beban kerja telah melebihi alokasi sumber daya database; tingkatkan tingkat layanan atau kurangi tingkat konkurensi.
40613 Database '%.*ls' on server '%.*ls' is not currently available. Please retry the connection later. If the problem persists, contact customer support, and provide them with the session tracing ID of '%.*ls'. Database tidak tersedia, biasanya saat failover sedang berlangsung atau sebentar selama operasi penskalaan. Coba lagi pada backoff; jika bertahan beberapa menit, ambil ID pelacakan sesi dan buka kasus dukungan.
42108 Can not connect to the SQL pool since it is paused. Please resume the SQL pool and try again. Kumpulan SQL terdedikasi (Synapse) berada dalam status dijeda. Percobaan ulang berhasil hanya setelah pool dilanjutkan kembali. Aktifkan kembali pool secara eksplisit, atau jadwalkan beban kerja agar berjalan setelah pool diaktifkan kembali.
42109 The SQL pool is warming up. Please try again. Pool SQL khusus sedang dilanjutkan. Coba kembali dengan jeda bertahap hingga pool aktif; inisialisasi awal biasanya memerlukan beberapa menit.
49918 Cannot process request. Not enough resources to process request. The service is currently busy. Please retry the request later. Server saat ini tidak dapat mengalokasikan sumber daya yang cukup untuk memenuhi permintaan. Coba lagi pada backoff. Jika kesalahan berlanjut, tingkatkan database atau kumpulan elastis.
49919 Cannot process create or update request. Too many create or update operations in progress for subscription "%ld". Batas konkurensi pada tingkat langganan untuk operasi manajemen. Kurangi panggilan pembuatan/pembaruan secara paralel atau beri jeda di antaranya.
49920 Cannot process request. Too many operations in progress for subscription "%ld". Batas konkurensi tingkat langganan pada operasi dalam penerbangan. Kurangi paralelisme atau tunggu hingga operasi dalam penerbangan terkuras.

Kesalahan pada tingkat pernyataan tidak ada dalam daftar ini karena kesalahan tersebut terjadi setelah koneksi terjalin dan kegagalan tersebut membuat sesi tetap dapat digunakan. Kesalahan pernyataan yang dapat dicoba ulang yang paling umum adalah 1205 (korban deadlock) dan 1222 (batas waktu permintaan penguncian). Ulangi seluruh transaksi alih-alih satu pernyataan yang gagal.

Teks pesan kesalahan berasal dari kesalahan koneksi sementara Azure SQL. Driver individual mempertahankan daftar coba lagi bawaan mereka sendiri; katalog ini menjelaskan kesalahan mana yang memenuhi syarat untuk mencoba kembali di SQL Server, Azure SQL Database, Azure SQL Managed Instance, database SQL di Microsoft Fabric, dan kumpulan SQL khusus di Azure Synapse Analytics.

Tidak dapat membuka server (firewall)

Pesan kesalahan:mssql: login error: Cannot open server '<server>' requested by the login. Client with IP address '203.0.113.42' is not allowed to access the server.

Penyebab dan solusi:

  • IP klien Anda tidak ada dalam aturan firewall Azure SQL. Tambahkan aturan firewall di portal Azure:Jaringan SQL>Server>Tambahkan aturan firewall.
  • Jika aplikasi Anda berjalan di Azure, aktifkan Izinkan layanan dan sumber daya Azure untuk mengakses server ini.
  • Untuk konektivitas privat, konfigurasikan titik akhir privat.

Batas sumber daya tercapai

Pesan kesalahan:mssql: Resource ID: 1. The session limit for the database is 300 and has been reached.

Penyebab dan solusi:

  • Terlalu banyak koneksi bersamaan untuk tingkat Azure SQL. Turunkan MaxOpenConns dalam konfigurasi pool Anda.
  • Kebocoran koneksi (baris data atau transaksi yang tidak ditutup). Periksa apakah ada panggilan defer rows.Close() atau defer tx.Rollback() yang hilang.
  • Beberapa aplikasi berbagi database. Bagi batas koneksi ke semua klien.

Untuk batas koneksi Azure SQL berdasarkan tingkatan, lihat Azure SQL Database.

Layanan saat ini sibuk (pembatasan)

Pesan kesalahan:mssql: The service is currently busy. Retry the request after 10 seconds. Code: 40501.

Penyebab dan solusi:

  • Basis data berada di bawah beban berat. Terapkan logika pengulangan dengan penundaan eksponensial.
  • Beban kerja melebihi kapasitas DTU atau vCore dari tingkatan tersebut. Pertimbangkan untuk meningkatkan skala.

Untuk pola implementasi coba lagi, lihat Penanganan kesalahan dan pola coba lagi.

Database saat ini tidak tersedia

Pesan kesalahan:mssql: Database 'AdventureWorks2025' on server '<server>' is not currently available. Code: 40613.

Penyebab: Azure SQL mengonfigurasi ulang database (operasi failover, pembaruan, atau penskalaan). Kondisi ini adalah kesalahan sementara.

Solusi: Coba lagi operasi. Database biasanya tersedia dalam hitungan detik. Untuk informasi selengkapnya, lihat Penanganan kesalahan dan pola coba lagi.

Kesalahan koneksi yang buruk

driver: bad connection Kesalahan berarti driver mendeteksi bahwa koneksi yang ada tidak lagi dapat digunakan. Kumpulan database/sql secara otomatis mencoba kembali operasi pada koneksi baru untuk panggilan non-transaksional, tetapi operasi di dalam transaksi aktif segera gagal.

Jangan mulai dengan bagian ini jika aplikasi tidak berhasil terhubung. driver: bad connection Biasanya menunjuk ke penggunaan kembali koneksi, failover, batas waktu idle, atau gangguan jaringan setelah koneksi awal sudah berfungsi.

Penyebab umum

Penyebab Skenario umum Perbaiki
Batas waktu idle gateway Azure SQL Koneksi menganggur selama 30+ menit di belakang gateway Azure. Atur db.SetConnMaxIdleTime(2 * time.Minute) untuk menggunakan kembali koneksi yang tidak aktif sebelum gateway memutusnya.
Gangguan jaringan Kegagalan jaringan sementara antara klien dan server. Terapkan logika coba lagi untuk operasi non-transaksional. Lihat Penanganan kesalahan.
Penghentian sesi di sisi server DBA mengakhiri sesi, atau server dimulai ulang. Coba lagi. Atur db.SetConnMaxLifetime untuk memutar koneksi.
Konfigurasi ulang Azure SQL Kejadian failover, penskalaan, atau penerapan patch menyebabkan koneksi terputus. Atur ConnMaxLifetime ke 5 menit atau kurang. Menerapkan logika pengulangan.
Batas waktu transaksi berdurasi lama Azure SQL mengakhiri sesi (kesalahan 40549). Jaga agar transaksi tetap singkat. Bagi operasi besar menjadi kelompok-kelompok yang lebih kecil.

Bagaimana database/sql menangani koneksi yang buruk

Untuk panggilan di luar transaksi (db.QueryContext, db.ExecContext), pool database/sql secara otomatis mencoba kembali operasi tersebut pada koneksi baru saat driver melaporkan koneksi bermasalah. Percobaan ulang ini transparan terhadap kode Anda.

Untuk panggilan dalam transaksi (tx.QueryContext, tx.ExecContext), pool tidak dapat mencoba ulang karena status transaksi hilang. Kode Anda harus menangani kesalahan, membatalkan, dan mencoba ulang seluruh transaksi.

Konfigurasikan pool untuk menangani timeout dan failover gateway Azure:

db.SetConnMaxLifetime(5 * time.Minute)  // Rotate connections to recover from failovers.
db.SetConnMaxIdleTime(2 * time.Minute)  // Recycle before Azure gateway drops idle connections (30 min).
db.SetMaxIdleConns(10)                  // Keep warm connections for quick recovery.
db.SetMaxOpenConns(20)                  // Stay below your tier's connection limit.

Untuk SQL Server lokal, ConnMaxIdleTime tidak terlalu penting karena tidak ada batas waktu habis sesi idle pada gateway. Namun, mengaturnya mencegah koneksi kedaluwarsa setelah gangguan jaringan.

Untuk panduan konfigurasi terperinci, lihat Azure SQL Database.

Kehabisan pool

Pool exhaustion terjadi ketika semua koneksi dalam pool sedang digunakan dan permintaan baru tertahan sambil menunggu koneksi.

Gejala

  • Permintaan melambat atau kehabisan waktu saat dibebani.
  • db.Stats().WaitCount tumbuh terus-menerus.
  • db.Stats().InUse MaxOpenConnssama dengan .
  • Tenggat waktu konteks melebihi kesalahan selama lalu lintas puncak.

Diagnosa

Tambahkan pemantauan kumpulan ke aplikasi Anda:

stats := db.Stats()
log.Printf("Pool: open=%d inUse=%d idle=%d waitCount=%d waitDuration=%v",
    stats.OpenConnections, stats.InUse, stats.Idle,
    stats.WaitCount, stats.WaitDuration)

Penyebab Umum dan Solusi

Penyebab Cara mengidentifikasi Perbaiki
rows.Close() tidak dipanggil InUse tumbuh seiring waktu, tidak pernah berkurang. Tambahkan defer rows.Close() setelah setiap QueryContext.
Transaksi jangka panjang InUse tetap tinggi selama pemrosesan batch. Jaga agar transaksi tetap singkat. Olah data dalam jumlah besar dalam bagian-bagian kecil.
MaxOpenConns terlalu rendah WaitCount tumbuh dengan stabil di bawah beban normal setelah Anda mengesampingkan sumber daya dan kebocoran yang disematkan. Tingkatkan MaxOpenConns.
MaxOpenConns tidak diatur Ratusan koneksi terbuka saat lonjakan beban. Atur MaxOpenConns ke nilai terbatas.
Panggilan kebocoran Goroutine db.Conn InUse tumbuh tanpa pertumbuhan permintaan yang sebanding. Pastikan setiap db.Conn() hasil ditutup dengan defer conn.Close().

Untuk panduan konfigurasi kumpulan terperinci, lihat Pengumpulan koneksi.

Diagnosis kueri yang lambat atau terblokir

Mengatur batas waktu kueri

Gunakan batas waktu konteks untuk mengidentifikasi kueri yang lambat dan mencegah panggilan SQL yang terblokir mengunci koneksi serta membuat pemanggil menunggu:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

rows, err := db.QueryContext(ctx, "SELECT * FROM LargeTable WHERE Status = @s",
    sql.Named("s", "active"))
if err != nil {
    // Check if the error was a timeout.
    if ctx.Err() == context.DeadlineExceeded {
        log.Println("Query exceeded 5-second timeout")
    }
    return err
}
defer rows.Close()

Untuk alur kerja investigasi performa lengkap, termasuk Query Store, DMV, analisis indeks yang hilang, dan pembandingan, lihat Penyetelan performa.

Diagnostik deadlock

Pesan kesalahan:mssql: Transaction (Process ID 52) was deadlocked on lock resources with another process and has been chosen as the deadlock victim. Rerun the transaction.

Nomor kesalahan: 1205

Solusi: Kebuntuan terjadi dalam sistem bersamaan. Terapkan logika coba ulang otomatis untuk kesalahan 1205. Untuk fungsi pembungkus untuk mencoba ulang deadlock, lihat Transaksi.

Strategi pencegahan:

  • Akses tabel dalam urutan yang sama di semua kueri.
  • Jaga agar transaksi tetap singkat dan hindari interaksi pengguna selama transaksi.
  • Gunakan READ COMMITTED SNAPSHOT isolasi untuk mengurangi pertentangan kunci.

Deadlock yang berulang pada kueri yang sama menunjukkan adanya masalah desain. Gunakan grafik deadlock (yang diperoleh melalui Extended Events atau sesi System Health) untuk mengidentifikasi pernyataan yang saling bersaing dan jenis kunci. Untuk panduan lengkap, lihat panduan deadlock. Untuk strategi penanganan kebuntuan di Go, lihat Penanganan kebuntuan dan Menangani kebuntuan.

Kesalahan sertifikat dengan kontainer (Go 1.23 dan versi yang lebih baru)

Pesan kesalahan:x509: negative serial number

Penyebab: Go 1.23 secara ketat menegakkan RFC 5280. Sertifikat yang ditandatangani sendiri yang dihasilkan SQL Server dalam kontainer Docker menggunakan nomor seri negatif, yang ditolak Go.

Solusi:

  • Untuk lingkungan pengujian, tambahkan TrustServerCertificate=true untuk melewati validasi sertifikat, atau encrypt=disable untuk menonaktifkan enkripsi sepenuhnya.
  • Untuk CI/CD, atur variabel GODEBUG=x509negativeserial=1 lingkungan untuk memulihkan perilaku pra-Go 1.23 tanpa mengubah string koneksi Anda.
  • Dalam go.mod (Go 1.23 dan versi yang lebih baru), tambahkan direktif godebug x509negativeserial=1 untuk menerapkan pengesampingan saat build.

Caution

Jangan gunakan TrustServerCertificate=true atau encrypt=disable dalam produksi. Opsi ini menonaktifkan pemeriksaan keamanan. Untuk produksi, gunakan sertifikat yang ditandatangani dengan benar.

Kesalahan sertifikat SHA-1 (Go 1.24 dan versi yang lebih baru)

Pesan kesalahan: tls: handshake failure atau TLS Handshake failed: EOF saat menyambungkan ke instans SQL Server yang lebih lama.

Penyebab: Go 1.24 tidak mengizinkan algoritme tanda tangan SHA-1 di sertifikat TLS secara default. Versi SQL Server yang lebih lama dan beberapa penginstalan lokal menggunakan sertifikat yang ditandatangani dengan SHA-1.

Solusi:

  • Terbitkan ulang sertifikat server dengan SHA-256 atau yang lebih baru (disarankan).
  • Atur variabel GODEBUG=tlssha1=1 lingkungan untuk mengaktifkan kembali dukungan SHA-1 untuk sementara.
  • Di go.mod (Go 1.23 dan versi yang lebih baru), tambahkan direktif godebug tlssha1=1 .

Kapan menggunakan encrypt=disable vs. TrustServerCertificate=true

Pengaturan Apa fungsinya Kapan digunakan
TrustServerCertificate=true Mengenkripsi lalu lintas tetapi melewati validasi sertifikat. Pengembangan dan pengujian lokal di mana server menggunakan sertifikat yang ditandatangani sendiri.
encrypt=disable Mengirim lalu lintas dalam teks biasa (tanpa TLS). Lingkungan lama tempat TLS tidak tersedia. Tidak disarankan.
encrypt=strict TDS 8.0 dengan validasi TLS penuh dari byte pertama. Produksi di SQL Server 2022 atau Azure SQL.

Untuk informasi selengkapnya, lihat Pengujian dan Enkripsi dan sertifikat.

Masalah pengkodean dan kolase

Peringatan konversi implisit

Jika Anda meneruskan string parameter (dikirim sebagai nvarchar) ke varchar kolom, SQL Server melakukan konversi implisit yang dapat mencegah penggunaan indeks.

Contoh ini melanjutkan penyiapan database/sql dan mssql dari cuplikan sebelumnya dalam artikel ini.

Solusi: Gunakan mssql.VarChar untuk varchar kolom:

db.QueryContext(ctx, "SELECT * FROM Production.Product WHERE ProductNumber = @p1",
    mssql.VarChar("FR-R92B-58"))

Kesalahan CharsetToUTF8 pada karakter non-Latin

Pesan kesalahan: CharsetToUTF8: ... saat mengkueri varchar kolom yang berisi karakter Cina, Jepang, atau non-Latin lainnya yang disimpan dalam kolase seperti SQL_Latin1_General_CP1_CI_AS.

Penyebab: Driver mencoba mengonversi halaman kode kolom ke UTF-8, tetapi byte yang disimpan tidak cocok dengan pengkodean yang diharapkan dari kolasi.

Solusi:

  • Gunakan nvarchar alih-alih varchar untuk kolom yang menyimpan teks non-Latin. nvarchar menyimpan data sebagai UTF-16 dan menghindari konversi halaman kode.
  • Jika Anda tidak dapat mengubah jenis kolom, pastikan penyusunan database mendukung kumpulan karakter yang Anda simpan.

Aktifkan pembuatan log diagnostik

Gunakan parameter koneksi log untuk mengaktifkan pencatatan log pada level driver:

sqlserver://<user>:<password>@<server>?database=AdventureWorks2025&log=63

Bendera log adalah nilai bitmask: 1 (kesalahan), 2 (pesan), 4 (baris), 8 (SQL), 16 (param), 32 (transaksi), 64 (debug). Gabungkan nilai dengan menambahkannya (misalnya, 63 = semua kecuali debug, 127 = semua).

Untuk pencatatan terprogram, gunakan SetLogger atau SetContextLogger. Lihat Pencatatan log dan diagnostik.

Daftar Periksa untuk Pemecahan Masalah

Gejala Langkah pertama
Koneksi ditolak Verifikasi SQL Server berjalan dan TCP/IP diaktifkan.
Gagal masuk Periksa kredensial dan mode otentikasi.
Kesalahan sertifikat Periksa sertifikat server atau atur TrustServerCertificate=true (khusus pengembang).
Waktu koneksi habis Verifikasi jalur jaringan dengan Test-NetConnection. Periksa aturan firewall.
Firewall Azure SQL Tambahkan IP Anda ke aturan firewall Azure SQL.
Kesalahan pembatasan kecepatan Terapkan coba lagi dengan penundaan eksponensial. Tingkatkan tingkatan.
Koneksi yang buruk Atur ConnMaxIdleTime di bawah 30 menit untuk Azure SQL. Menerapkan logika pengulangan.
Kehabisan pool Pantau db.Stats(). Perbaiki baris/transaksi yang belum ditutup. Tingkatkan MaxOpenConns.
Kueri lambat Tetapkan batas waktu konteks. Kueri DMVs untuk kueri yang mahal.
Kebuntuan Terapkan coba lagi pada kesalahan 1205. Akses tabel dalam urutan yang konsisten.
Konversi implisit Gunakan mssql.VarChar untuk varchar kolom.

Konten terkait

  • Last updated on