go-mssqldb sürücüsünde sorun giderme

Bu makale, sürücüyle ilgili yaygın hatalar ve bağlantı sorunları go-mssqldb için çözümler sunmaktadır.

En basit kontrollerle başlayın

Ayrıntılı kayıt işlemlerini etkinleştirmeden veya havuz ayarlarını değiştirmeden önce aşağıdaki listeyi gözden geçirin:

1. Temel erişilebilirliği doğrulayın: sunucu adı, port, güvenlik duvarı kuralları ve SQL Server veya Azure SQL'in bağlantıları kabul edip etmediği.
2. Kimlik doğrulama girdilerini doğrulayın: sürücü adı, kullanıcı adı, şifre, alan adı formatı veya fedauth yapılandırma.
3. TLS ayarlarını doğrulayın: encrypt, sertifika yolları, hostnameincertificate, ve ortam için uygun olup olmadığını TrustServerCertificate doğrulayın.
4. Yalnızca bağlantı kurulumu doğru olduktan sonra, bağlantı havuzunun tükenmesini, eskimiş bağlantıları, yeniden deneme mantığını ve yavaş veya engellenmiş sorguların teşhisini inceleyin.

Bağlantı kurulumu hataları için bu makalenin ilk bölümlerini kullanın. İlerleyen bölümleri yalnızca bağlantılar en azından bazen başarıyla kuruluyorsa ve ardından yük altında, boşta kalma süresinden sonra veya yük devretme sırasında başarısız oluyorsa kullanın.

Bağlantı hataları

Aşağıdaki bölümler, yaygın bağlantı kaynaklı hata mesajlarını ve bunların çözümlerini ele alır.

TCP bağlantısı açılamıyor

Hata iletisi: 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.

Nedenler ve çözümler:

• SQL Server çalışmıyor. SQL Server hizmetini başlatın.
• TCP/IP etkin değil. SQL Server Yapılandırma Yöneticisi'ı açın ve SQL Server Network Configuration>Protocols altında TCP/IP'yi etkinleştirin.
• Yanlış liman. SQL Server Yapılandırma Yöneticisi'da portu doğrulayın veya adlandırılmış örnekler için SQL Server Browser kullanın.
• Güvenlik duvarı portu engelliyor. 1433 portu (veya yapılandırılmış portunuz) için bir gelen kuralı ekleyin.

Kullanıcı için oturum açılamadı

Hata iletisi: mssql: login error: Login failed for user '<user>'.

Nedenler ve çözümler:

• Yanlış kullanıcı adı veya şifre. Kimlik bilgilerini doğrulayın.
• SQL Server doğrulaması devre dışı bırakılmıştır. Sunucu özelliklerinde SQL Server ve Windows Kimlik Doğrulama modunu etkinleştirin.
• Giriş yok. SQL Server'da giriş oluşturun.
• Oturum açma hesabının hedef veritabanına erişimi yok. Veritabanına erişim izni ver.CREATE USER

Sertifika doğrulama hataları

Hata iletisi: TLS Handshake failed: x509: certificate signed by unknown authority

Nedenler ve çözümler:

• Sunucu, kendi kendine imzalanmış bir sertifika kullanır. Sertifika yolunu certificate veya serverCertificate parametresiyle belirtin ya da yalnızca geliştirme için TrustServerCertificate=true değerini ayarlayın.
• CA sertifikası sistem güven deposunda değil. CA sertifikasını işletim sistemi güven deposuna ekleyin veya parametreyle certificate belirtin.
• Sunucu ismi uyumsuzluğu. Sertifikada beklenen ismi belirtmek için kullanılır hostnameincertificate .

Daha fazla bilgi için Şifreleme ve sertifikalar bölümünü inceleyin.

Bağlantı zaman aşımı süresi doldu

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

Nedenler ve çözümler:

• Ağ bağlantısı sorunları. telnet <server> 1433 veya Test-NetConnection -ComputerName <server> -Port 1433 kullanarak sunucuya ulaşabildiğinizi doğrulayın.
• DNS çözümleme hatası. Ana bilgisayar adının doğru çözüldüğünü doğrulayın.
• Bağlantı dizesinde dial timeout veya connection timeout değerini artırın.

Kimlik doğrulama hataları

Aşağıdaki bölümler kimlik doğrulama hata mesajlarını kapsar.

NTLM kimlik doğrulama hataları

Hata iletisi: NTLM authentication failed

Nedenler ve çözümler:

• Yanlış alan adı formatı. user id parametresinde DOMAIN\user kullanın. URL formatında, ters eğik çizgiyi şu şekilde %5Ckodlayın.
• Yanlış şifre. Alan şifresini doğrulayın.

Kerberos kimlik doğrulama hataları

Hata iletisi: krb5: cannot resolve KDC for realm

Nedenler ve çözümler:

• Eksik ya da yanlış yapılandırılmış /etc/krb5.conf. Bölümde [realms] alan alanınız için doğru KDC adresini içerdiğinden emin olun.
• Geçerli bilet yok. Geçerli bir biletin olup olmadığını denetlemek için klist komutunu çalıştırın veya bir bilet almak için kinit komutunu çalıştırın.
• Keytab dosyası bulunamadı. Parametredeki krb5-keytabfile yolu doğrulayın.

Daha fazla bilgi için SQL Server ve Windows authentication bölümlerine bakınız.

Microsoft Entra ID kimlik doğrulama hataları

Hata mesajı: clientCredentialFromCert: error reading certificate: ... veya DefaultAzureCredential: failed to acquire a token

Nedenler ve çözümler:

• Yanlış müşteri kimliği, kiracı kimliği veya müşteri sırrı. Bağlantı dizesindeki veya ortam değişkenlerindeki değerleri doğrulayın.
• Yönetilen kimlik, ana bilgisayarda yapılandırılmamış. Azure portalında kimliği doğrulayın.
• Eksik azuread paket içe aktarma. github.com/microsoft/go-mssqldb/azuread öğesini içe aktarın ve azuresql sürücü adını kullanın.

Daha fazla bilgi için bkz. Microsoft Entra Id kimlik doğrulaması.

Kullanıcı '' (boş kullanıcı adı) için giriş başarısız oldu

Hata iletisi: mssql: login error: Login failed for user ''.

Sebep: sql.Open("sqlserver", ...) öğesini fedauth parametresiyle kullandınız. Entra ID doğrulaması için sürücü adının paket azuresql tarafından kaydedilmesi gerekirazuread. Standart sqlserver sürücü ile parametre fedauth göz ardı edilir ve sürücü kullanıcı adı olmadan SQL kimlik doğrulaması dener.

Çözüm: Paketi azuread içe aktarın ve sürücü azuresql adını kullanın:

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

Daha fazla bilgi için bkz. Microsoft Entra Id kimlik doğrulaması.

Sorgu hataları

Aşağıdaki bölümler sorgu yürütme hata mesajlarını kaplar.

LastInsertId desteklenmiyor

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

Çözüm: go-mssqldb sürücüsü, LastInsertId() öğesini desteklemiyor. OUTPUT yan tümcesini veya SCOPE_IDENTITY() sorgusunu ayrı kullanın.

Geçici tablo bulunamadı

Hata iletisi: mssql: Invalid object name '#TempTable'.

Sebep: Geçici tablolar bağlantı bazındadır. Bir çağrıda geçici bir tablo oluşturup başka bir çağrıda sorgularsanız, havuzdan farklı bağlantılar kullanabilirler.

Çözüm: Tek bir bağlantıya sabitlemek için db.Conn(ctx) kullanın veya işlemleri bir işlem içinde gerçekleştirin.

Daha fazla bilgi için bkz: Saklı yordamlar.

Azure SQL hataları

Aşağıdaki bölümler Azure SQL Veritabanı'e özgü hataları kapsar.

Geçici bağlantı hata numaraları

Sınırlı yeniden denemeye uygun geçici bağlantı kurma hataları ve istek yolu taşıma hataları için aşağıdaki paylaşılan listeyi referans olarak kullanın:

Aşağıdaki hatalar, bağlantı kurulması sırasında veya sunucuya istek gönderilirken ortaya çıktığında geçicidir. Kısa, sınırlanmış geri çekilmeyi yeniden deneyin. Birkaç yeniden denemeden sonra kalıcı olan hatalar genellikle yeniden denemenin düzeltmeyeceği bir yapılandırma sorununu (yanlış sunucu, eksik izinler, tükenmiş kota) gösterir.

Error	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.)	TCP bağlantısı el sıkışma işleminin ortasında kesilir. Kimlik bilgileriyle ilgili bir hata değil. Sorun devam ederse, istemci tarafındaki ağ kararsızlığını veya yarım kurulmuş bağlantıları sonlandıran bir ara cihaz olup olmadığını kontrol edin.
233	The client was unable to establish a connection because of an error during connection initialization process before login.	Oturum açma öncesi aktarım veya TLS hatası. Sunucu genellikle bağlantıyı kabul etmediğinde (kaynak tükenmesi, maksimum bağlantılara ulaşılması veya desteklenmeyen bir istemci) döndürür. Kimlik bilgileriyle ilgili bir hata değil. Sunucu durumunu doğrulayın, ardından istemci oturum açma zaman aşımını, TLS ayarlarını ve istemci/sunucu TLS sürüm uyumluluğunu denetleyin.
4060	Cannot open database "%.*ls" requested by the login. The login failed.	Oturum açma kimliği doğrulanır ancak istenen veritabanını açamaz. Geçici nedenler arasında veritabanının bir geçiş durumunda olması (yük devretme, geri yükleme, ölçeklendirme) veya otomatik olarak duraklatılmış olması yer alır. Kalıcı nedenler (veritabanı mevcut değil, oturum açma erişimi yok) yeniden denenerek düzeltilmez; veritabanı adını, oturum açma eşlemesini ve veritabanı durumunu denetleyin.
4221	Login to read-secondary failed due to long wait on 'HADR_DATABASE_WAIT_FOR_TRANSITION_TO_VERSIONING'.	Çoğaltma geri dönüştürüldükleri sırada uçuşta olan işlemler için satır sürümleri eksik olduğundan çoğaltma oturum açma için kullanılamaz. Sorunu çözmek için birincil üzerindeki aktif işlemleri geri alın veya onaylayın. Birincil üzerinde uzun yazma işlemlerinden kaçınarak etkisini azaltın.
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.)	Yerel taraf bağlantıyı durdurur. İstemci tarafı ağ durumunu ve herhangi bir yerel güvenlik duvarını veya VPN istemcilerini denetleyin.
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.)	Uzak taraf bir TCP sıfırlaması gönderir. Yaygın nedenler: eş süreç çöktü, bir güvenlik duvarı bir sıfırlama paketi gönderdi veya Azure SQL ağ geçidi boşta olan bir bağlantıyı kapattı. Bağlantının boştayken sıfırlanması durumlarında, istemcide TCP keepalive’ı etkinleştirin veya bağlantı havuzundaki boşta kalma zaman aşımını kısaltın.
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.	Veritabanı Azure SQL kaynak idare sınırını aşıyor. Kaynak Kimliği 1, çalışan sınırını gösterir; Kaynak Kimliği 2, oturum sınırını gösterir. İletideki sınır türünü belirleyin, ardından eşzamanlılığı azaltın, veritabanının ölçeğini genişletin veya kaynağı tutan uzun süre çalışan işlemleri kısaltın.
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.	Veritabanı minimum garanti düzeyini aştı ve altyapıdaki sunucu kısıtlama uyguluyor. Yeniden deneme genellikle komşu yükü düştüğünde başarılı olur. Sürekli oluşumlar, daha yüksek bir hizmet katmanına veya daha az gürültülü bir ortama ihtiyacınız olduğunu gösterir.
40020, 40143, 40166, 40540	Yük devretme sırasında oluşan 40197 hatasının Error code %d alanında bildirildi.	Bazı yolların üst düzey hata numarası olarak göründüğü 40197 yük devretme iletisine eklenmiş alt kodlar. Bunları 40197 ile aynı şekilde değerlendirin.
40197	The service has encountered an error processing your request. Please try again. Error code %d.	Azure SQL’de bir yazılım yükseltmesi, donanım arızası veya başka bir yük devretme durumu. Yeniden bağlanma sizi sağlıklı bir kopyaya yönlendirir. Eklenen hata kodu yük devretme türünü tanımlar. Hata devam ederse oturum izleme kimliğini yakalayın ve desteğe başvurun.
40501	The service is currently busy. Retry the request after 10 seconds. Incident ID: %ls. Code: %d.	Azure SQL motor azaltma. Önerilen minimum bekleme süresi 10 saniyedir. Sürekli kısıtlama, iş yükünün veritabanının kaynak tahsisini aştığını gösterir; hizmet katmanını yükseltin veya eşzamanlılığı azaltın.
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'.	Veritabanı, genellikle yük devretme sırasında veya ölçeklendirme işlemi sırasında kısa bir süreliğine kullanılamaz. Artan aralıklarla yeniden deneyin; sorun birkaç dakikadan uzun sürerse oturum izleme kimliğini kaydedin ve bir destek kaydı oluşturun.
42108	Can not connect to the SQL pool since it is paused. Please resume the SQL pool and try again.	Ayrılmış SQL havuzu (Synapse) duraklatılmış durumda. Yeniden deneme yalnızca havuz yeniden etkinleştirildikten sonra başarılı olur. Havuzu açıkça yeniden etkinleştirin veya iş yükünü, havuz yeniden etkinleştirildikten sonra çalışacak şekilde zamanlayın.
42109	The SQL pool is warming up. Please try again.	Ayrılmış SQL havuzu yeniden başlatılıyor. Havuz çevrimiçi olana kadar geri çekilmeyi yeniden deneyin; ısınma genellikle birkaç dakika sürer.
49918	Cannot process request. Not enough resources to process request. The service is currently busy. Please retry the request later.	Sunucu şu anda isteği karşılamak için yeterli kaynak ayıramıyor. Geri alma işlemini yeniden deneyin. Hata devam ederse veritabanının veya elastik havuzun ölçeğini büyütün.
49919	Cannot process create or update request. Too many create or update operations in progress for subscription "%ld".	Yönetim işlemlerinde abonelik düzeyinde eşzamanlılık sınırı. Paralel oluşturma/güncelleştirme çağrılarını azaltın veya bunları kademeleyin.
49920	Cannot process request. Too many operations in progress for subscription "%ld".	Uçuştaki işlemlerde abonelik düzeyinde eşzamanlılık sınırı. Paralelliği azaltın veya uçuş içi işlemlerin boşalmasını bekleyin.

İfade düzeyindeki hatalar, bağlantı kurulduktan sonra ortaya çıktıkları ve hata sonrasında oturum kullanılabilir durumda kaldığı için bu listede yer almıyor. En yaygın yeniden denenebilir ifade hataları 1205 (deadlock kurbanı) ve 1222'dir (kilit isteği zaman aşımı). Başarısız olan tek bir komut yerine işlemin tamamını yeniden deneyin.

Hata iletisi metni Azure SQL geçici bağlantı hatalarından kaynaklanır. Her sürücü kendi yerleşik yeniden deneme listesine sahiptir; bu katalog, SQL Server, Azure SQL Veritabanı, Azure SQL Yönetilen Örneği, Microsoft Fabric’teki SQL veritabanı ve Azure Synapse Analytics’teki ayrılmış SQL havuzları genelinde hangi hataların yeniden deneme için uygun olduğunu açıklar.

Sunucu açamıyor (güvenlik duvarı)

Hata iletisi: 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.

Nedenler ve çözümler:

• İstemcinizin IP adresi Azure SQL güvenlik duvarı kurallarında yok. Azure portalında bir güvenlik duvarı kuralı ekleyin: SQL server>Ağ Oluşturma>Güvenlik duvarı kuralı ekle.
• Uygulamanız Azure'da çalışıyorsa, bu sunucuya erişim için Azure hizmetlerine ve kaynaklarına izin verin.
• Özel bağlantı için özel uç noktası yapılandırın.

Kaynak sınırına ulaşıldı

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

Nedenler ve çözümler:

• Azure SQL tier'i için çok fazla eşzamanlı bağlantı var. Havuz konfigürasyonunda daha düşük MaxOpenConns bir seviyeye bırakın.
• Bağlantı sızıntıları (kapatılmamış satırlar veya işlemler). Eksik defer rows.Close() veya defer tx.Rollback() çağrıları olup olmadığını kontrol edin.
• Veritabanını paylaşan birden fazla uygulama. Bağlantı sınırını tüm istemciler arasında böl.

Azure SQL bağlantı sınırları için katmana göre Azure SQL Veritabanı konusuna bakın.

Hizmet şu anda yoğun (kısıtlama uygulanıyor)

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

Nedenler ve çözümler:

• Veritabanı ağır yük altında. Üstel geri çekilme ile yeniden deneme mantığını uygulayın.
• İş yükü, seviyenin DTU veya vCore kapasitesini aşıyor. Ölçeklendirmeyi düşün.

Yeniden deneme uygulama kalıpları için bkz. Hata işleme ve tekrar deneme kalıpları.

Veritabanı şu anda mevcut değildir

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

Sebep: Azure SQL veritabanını yeniden yapılandırıyor (failover, güncelleme veya ölçeklendirme işlemi). Bu koşul geçici bir hatadır.

Çözüm: İşlemi tekrar dene. Veritabanı genellikle saniyeler içinde erişilebilir hale gelir. Daha fazla bilgi için Hata işleme ve tekrar deneme kalıpları bölümlerine bakınız.

Kötü bağlantı hataları

Hata, driver: bad connection sürücünün mevcut bir bağlantının artık kullanılamaz olduğunu tespit ettiği anlamına gelir. database/sql havuz, işlem kapsamında olmayan çağrılar için işlemi yeni bir bağlantı üzerinden otomatik olarak yeniden dener, ancak etkin bir işlem içindeki işlemler anında başarısız olur.

Uygulama hiç başarılı bağlanmadıysa bu bölümle başlamayın. driver: bad connection genellikle bağlantının yeniden kullanılması, yük devretme, boşta kalma zaman aşımı veya ilk bağlantı zaten çalışmaya başladıktan sonraki ağ kesintilerine işaret eder.

Yaygın nedenler

Cause	Tipik senaryo	Düzelt
Azure SQL ağ geçidi boşta kalma zaman aşımı	Azure gateway'in arkasında 30+ dakika boyunca bağlantı boşta kalır.	db.SetConnMaxIdleTime(2 * time.Minute) değerini, ağ geçidi atıl bağlantıları sonlandırmadan önce geri dönüştürecek şekilde ayarlayın.
Ağ kesintisi	İstemci ile sunucu arasında geçici ağ arızası.	İşlemsel olmayan işlemler için yeniden deneme mantığını uygulayın. Hata işleme bölümüne bakınız.
Sunucu tarafı oturum sonlandırma	DBA oturumu kapattı ya da sunucu yeniden başlatıldı.	Yeniden deneyin. Bağlantıları döndürmek için db.SetConnMaxLifetime olarak ayarlayın.
Azure SQL yeniden yapılandırması	Yük devretme, ölçeklendirme veya yama işlemi bağlantının kesilmesine neden oldu.	5 dakika veya daha kısa süreye ayarlayın ConnMaxLifetime . Yeniden deneme mantığını uygulayın.
Uzun süreli işlem zaman aşımı	Azure SQL oturumu sonlandırdı (error 40549).	İşlemleri kısa tutun. Büyük işlemleri daha küçük toplu işlemlere ayırın.

Veritabanı/SQL kötü bağlantıları nasıl yönetiyor

Bir işlem dışındaki çağrılar için (db.QueryContext, db.ExecContext), sürücü kötü bağlantı bildirdiğinde, database/sql havuz otomatik olarak yeni bir bağlantıda işlemi yeniden dener. Bu yeniden deneme işlemi kodunuz tarafından fark edilmez.

Bir işlem içindeki çağrılarda (tx.QueryContext, tx.ExecContext), havuz yeniden deneyemez çünkü işlem durumu kaybolur. Kodunuz hatayı yakalamalı, geri almalı ve tüm işlemi tekrar denemeli.

Azure SQL için önerilen havuz ayarları

Azure ağ geçidi zaman aşımlarını ve yük devretmelerini işleyecek şekilde havuzu yapılandırın:

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.

Şirket içi SQL Server için ConnMaxIdleTime daha az kritiktir çünkü ağ geçidi için boşta kalma zaman aşımı yoktur. Ancak bunu ayarlamak, ağ kesintilerinden sonra eskimiş bağlantıları önler.

Detaylı yapılandırma rehberliği için bkz. Azure SQL Veritabanı.

Havuz tükenmesi

Havuz tükenmesi, havuzdaki tüm bağlantılar kullanıldığında ve yeni arayanların bağlantı beklerken bloklanmasıyla ortaya çıkar.

Symptoms

• İstekler yüklenirken yavaşlıyor veya zaman bitiyor.
• db.Stats().WaitCount sürekli büyür.
• db.Stats().InUse eşittir MaxOpenConns.
• Bağlam son tarihi, trafik zirvesinde hataları aştı.

Tanı

Uygulamanıza havuz izleme ekleyin:

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)

Yaygın nedenler ve çözümler

Cause	Nasıl tanımlanır?	Düzelt
rows.Close() çağrılmaz	InUse zamanla büyür, asla azalmaz.	Her QueryContext öğesinden sonra defer rows.Close() ekleyin.
Uzun süreli işlemler	InUse toplu işlem sırasında yüksek olmaya devam eder.	İşlemleri kısa tutun. Büyük partileri daha küçük parçalar halinde işleyin.
MaxOpenConns Çok düşük	WaitCount sabitlenmiş kaynakları ve sızıntıları eledikten sonra normal yük altında istikrarlı biçimde artar.	Artırın MaxOpenConns.
MaxOpenConns ayarlanmadı	Ani yük artışı sırasında yüzlerce açık bağlantı.	MaxOpenConns sınırlı bir değere ayarlayın.
Goroutine sızıntı çağrısı db.Conn	InUse karşılık gelen talep büyümesi olmadan büyür.	Her db.Conn() sonucun defer conn.Close() ile kapatıldığından emin olun.

Detaylı havuz yapılandırma rehberliği için bkz. Bağlantı havuzlama.

Yavaş veya engellenen sorgu tanılama

Sorgu zaman aşımlarını ayarlayın

Yavaş sorguları belirlemek ve engellenen SQL çağrılarının bağlantıları meşgul ederek çağıran işlemlerin beklemesine yol açmasını önlemek için bağlam zaman aşımı sınırlarını kullanın:

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

Query Store, DMV'ler, eksik dizin analizi ve kıyaslama dahil olmak üzere tam bir performans inceleme iş akışı için Performans ayarlama konusuna bakın.

Deadlock tanılaması

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

Hata numarası: 1205

Çözüm: Kilitlenmeler eşzamanlı sistemlerde meydana gelir. 1205 hatası için otomatik yeniden deneme mantığı uygulan. Deadlock yeniden deneme sarmalayıcı işlevi için Transactions'a bakınız.

Önleme stratejileri:

• Tüm sorgularda tablolara aynı sırayla erişin.
• İşlemleri kısa tutun ve işlemler sırasında kullanıcı etkileşiminden kaçının.
• Kilit çekişmesini azaltmak için READ COMMITTED SNAPSHOT izolasyon kullanın.

Aynı sorguda tekrarlanan kilitlenmeler, bir tasarım sorununa işaret eder. Çakışan ifadeleri ve kilit türlerini belirlemek için, Extended Events veya sistem durumu oturumu aracılığıyla yakalanan kilitlenme grafiğini kullanın. Tam bir rehber için Deadlocks rehberine bakabilirsiniz. Go'da deadlock handling stratejileri için bkz. Deadlock handling ve Handle deadlocks.

Konteynerlerde sertifika hataları (Go 1.23 ve daha sonraki sürümler)

Hata iletisi: x509: negative serial number

Sebep: Go 1.23, RFC 5280'i sıkı şekilde uygular. SQL Server'ın Docker konteynerlerinde oluşturduğu kendi kendine imzalanan sertifika, Go tarafından reddedilen negatif seri numarası kullanır.

Çözümler:

• Test ortamları için, sertifika doğrulamasını atlamak veya TrustServerCertificate=true şifrelemeyi tamamen kapatmak için ekleyinencrypt=disable.
• CI/CD için, ortam değişkenini GODEBUG=x509negativeserial=1 bağlantı dizesi'inizi değiştirmeden öncesi Go 1.23 davranışını geri yüklemek için ayarlayın.
• go.mod içinde (Go 1.23 ve sonraki sürümlerde), bu geçersiz kılma işlemini derleme sırasında uygulamak için bir godebug x509negativeserial=1 yönergesi ekleyin.

Dikkat

TrustServerCertificate=true veya encrypt=disable'i canlı ortamda kullanmayın. Bu seçenekler güvenlik kontrollerini devre dışı bırakır. Üretim için, doğru imzalanmış bir sertifika kullanın.

SHA-1 sertifika hataları (Go 1.24 ve daha sonraki sürümler)

Hata mesajı: tls: handshake failure veya TLS Handshake failed: EOF eski SQL Server örneklerine bağlanırken.

Sebep: Go 1.24, varsayılan olarak TLS sertifikalarında SHA-1 imza algoritmalarına izin vermiyor. Eski SQL Server sürümleri ve bazı on-premises kurulumlar SHA-1 ile imzalanmış sertifikalar kullanır.

Çözümler:

• Sunucu sertifikasını SHA-256 veya daha sonrası ile yeniden yayınlayın (önerilir).
• Ortam değişkenini GODEBUG=tlssha1=1 geçici olarak SHA-1 desteğini yeniden etkinleştirecek şekilde ayarlayın.
• go.mod (Go 1.23 ve daha sonraki sürümlerde) bir godebug tlssha1=1 direktifi ekleyin.

encrypt=disable ve TrustServerCertificate=true ne zaman kullanılır

Ayarlar	Ne işe yarıyor?	Ne zaman kullanılır?
TrustServerCertificate=true	Trafiği şifreler ancak sertifika doğrulamasını atlar.	Sunucunun kendi kendine imzalanmış bir sertifika kullandığı yerel geliştirme ve test.
encrypt=disable	Trafik açık metin olarak gönderilir (TLS yoktur).	TLS'nin mevcut olmadığı eski ortamlar. Tavsiye edilmez.
encrypt=strict	İlk bayttan itibaren tam TLS doğrulamalı TDS 8.0.	SQL Server 2022 veya Azure SQL üzerinde üretim.

Daha fazla bilgi için Testleme ve Şifreleme ve sertifikalar bölümlerine bakınız.

Kodlama ve derleme sorunları

Örtük dönüşüm uyarıları

Parametreleri (nvarchar olarak gönderilen) varchar sütunlara string iletirseniz, SQL Server dizin kullanımını engelleyebilecek örtük bir dönüştürme gerçekleştirir.

Bu örnek, bu makaledeki önceki kod parçacıklarında yer alan database/sql ve mssql kurulumunu sürdürür.

Çözüm: varchar sütunları için mssql.VarChar kullanın:

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

Latin olmayan karakterlerde CharsetToUTF8 hatası

Hata mesajı: CharsetToUTF8: ...varchar Çince, Japonca veya diğer Latin olmayan karakterleri içeren sütunları sorgularken, örneğin SQL_Latin1_General_CP1_CI_ASbir derlemede saklanır.

Sebep: Sürücü, sütunun kod sayfasını UTF-8'e dönüştürmeye çalışır, ancak saklanan baytlar derlemenin beklenen kodlamasıyla eşleşmez.

Çözümler:

• Latince olmayan metin depolayan sütunlar yerine nvarchar kullanınvarchar. nvarchar verileri UTF-16 olarak saklar ve kod sayfası dönüşümünden kaçınır.
• Sütun tipini değiştiremiyorsan, veritabanı derlemesinin sakladığın karakter setini desteklediğini doğrula.

Tanılama kayıtlarını etkinleştir

log Bağlantı parametresini kullanarak sürücü düzeyinde kayıt işlemlerini etkinleştirin:

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

Log bayrakları bitmaske değerleridir: 1 (hatalar), 2 (mesajlar), 4 (satırlar), 8 (SQL), 16 (paramlar), 32 (işlemler), 64 (hata hata ayıklama). Değerleri toplayarak birleştirin (örneğin, 63 = debug dışındaki tümü, 127 = tümü).

Programatik loglama için SetLogger veya SetContextLogger kullanın. Bkz. Günlüğe kaydetme ve tanılama.

Sorun Giderme Kontrol Listesi

Belirti	İlk adım
Bağlantı reddedildi	SQL Server'ın çalıştığını ve TCP/IP'nin etkin olduğunu doğrulayın.
Oturum açılamadı	Kimlik bilgilerini ve kimlik doğrulama modunu kontrol edin.
Sertifika hatası	Sunucu sertifikasını kontrol edin veya TrustServerCertificate=true olarak ayarlayın (yalnızca geliştirme için).
Bağlantı zaman aşımına uğradı	Test-NetConnection ile ağ yolunu doğrulayın. Güvenlik duvarı kurallarını denetleyin.
Azure SQL güvenlik duvarı	IP'nizi Azure SQL firewall kurallarına ekleyin.
Kısıtlama Hataları	Üstel geri çekilme ile yeniden deneme uygula. Kademeyi yükselt.
Kötü bağlantı	Azure SQL için ConnMaxIdleTime değerini 30 dakikanın altında ayarlayın. Yeniden deneme mantığını uygulayın.
Havuz tükenmesi	Monitör db.Stats(). Kapatılmamış satırlar/işlemleri düzeltin. Artırın MaxOpenConns.
Yavaş sorgular	Bağlam zaman aşımlarını ayarlayın. Yüksek maliyetli sorgular için DMV'leri sorgulayın.
Deadlocks	1205 hatasında yeniden deneme uygula. Tablolara tutarlı sırayla erişin.
Örtük dönüşüm	varchar sütunları için mssql.VarChar kullanın.

İlgili içerik

• Hata yönetimi ve tekrar deneme kalıpları
• Bağlantı havuzu oluşturma
• Azure SQL Veritabanı
• İşlemler
• Günlük ve teşhis
• Bilinen sınırlamalar