Fehlerbehebung des go-mssqldb-Treibers

Dieser Artikel bietet Lösungen für häufige Fehler und Verbindungsprobleme mit dem go-mssqldb Treiber.

Fang mit den einfachsten Prüfungen an

Bevor Sie das Verbose-Logging aktivieren oder die Pool-Einstellungen ändern, arbeiten Sie sich die folgende Liste an:

1. Überprüfen Sie die grundlegende Erreichbarkeit: Servername, Port, Firewall-Regeln und ob SQL Server oder Azure SQL Verbindungen akzeptiert.
2. Überprüfen Sie die Authentifizierungseingaben: Treibername, Benutzername, Passwort, Domänenformat oder fedauth Konfiguration.
3. Überprüfen Sie TLS-Einstellungen: encrypt, Zertifikatspfade, hostnameincertificate, und ob TrustServerCertificate sie für die Umgebung geeignet sind.
4. Erst wenn die Verbindung korrekt eingerichtet ist, sollten Sie die Erschöpfung des Verbindungspools, veraltete Verbindungen, die Wiederholungslogik sowie die Diagnose langsamer oder blockierter Abfragen untersuchen.

Verwenden Sie bei Fehlern bei der Einrichtung der Verbindung die ersten Abschnitte dieses Artikels. Verwenden Sie die späteren Abschnitte nur dann, wenn Verbindungen zumindest gelegentlich erfolgreich hergestellt werden und dann unter Last, nach einer Leerlaufzeit oder bei einem Failover ausfallen.

Verbindungsfehler

Die folgenden Abschnitte behandeln häufige verbindungsbezogene Fehlermeldungen und deren Lösungen.

TCP-Verbindung kann nicht geöffnet werden

Fehlermeldung: 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.

Ursachen und Lösungen:

• SQL Server läuft nicht. Starten Sie den SQL Server-Dienst.
• TCP/IP ist nicht aktiviert. Öffnen Sie den SQL Server-Konfigurations-Manager und aktivieren Sie TCP/IP unter den SQL Server Network Configuration>Protocols.
• Falscher Hafen. Verifizieren Sie den Port im SQL Server-Konfigurations-Manager oder verwenden Sie den SQL Server Browser für benannte Instanzen.
• Firewall blockiert den Port. Füge eine eingehende Regel für Port 1433 (oder deinen konfigurierten Port) hinzu.

Anmeldung für Benutzer fehlgeschlagen

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

Ursachen und Lösungen:

• Falscher Benutzername oder Passwort. Überprüfe die Zugangsdaten.
• Die SQL Server-Authentifizierung ist deaktiviert. Aktivieren Sie SQL Server und den Windows-Authentifizierungsmodus in den Servereigenschaften.
• Der Login existiert nicht. Erstelle den Login in SQL Server.
• Der Login hat keinen Zugriff auf die Zieldatenbank. Datenbankzugriff gewähren mit CREATE USER.

Fehler bei der Zertifikatüberprüfung

Fehlermeldung: TLS Handshake failed: x509: certificate signed by unknown authority

Ursachen und Lösungen:

• Der Server verwendet ein selbstsigniertes Zertifikat. Geben Sie den Zertifikatspfad mit dem Parameter certificate oder serverCertificate an, oder setzen Sie TrustServerCertificate=true nur für die Entwicklung.
• Das CA-Zertifikat befindet sich nicht im System-Vertrauensspeicher. Füge das CA-Zertifikat dem OS-Trust Store hinzu oder gib es mit dem Parameter certificate an.
• Hostname stimmt nicht überein. Verwenden Sie hostnameincertificate, um den erwarteten Namen im Zertifikat anzugeben.

Weitere Informationen finden Sie unter Verschlüsselung und Zertifikate.

Verbindungstimeout abgelaufen

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

Ursachen und Lösungen:

• Probleme mit der Netzwerkverbindung. Vergewissern Sie sich, dass Sie den Server mit telnet <server> 1433 oder Test-NetConnection -ComputerName <server> -Port 1433 erreichen können.
• DNS-Auflösungsfehler. Überprüfen Sie, ob der Hostname korrekt aufgelöst wird.
• Erhöhen Sie dial timeout oder connection timeout in der Verbindungszeichenfolge.

Authentifizierungsfehler

Die folgenden Abschnitte behandeln Authentifizierungsfehlermeldungen.

NTLM-Authentifizierungsfehler

Fehlermeldung: NTLM authentication failed

Ursachen und Lösungen:

• Falsches Domain-Format. Verwenden Sie DOMAIN\user im Parameter user id. Im URL-Format kodiert man den Backslash als %5C.
• Falsches Passwort. Überprüfen Sie das Domain-Passwort.

Kerberos-Authentifizierungsfehler

Fehlermeldung: krb5: cannot resolve KDC for realm

Ursachen und Lösungen:

• /etc/krb5.conf fehlt oder ist falsch konfiguriert. Überprüfen Sie, ob der [realms] Abschnitt die korrekte KDC-Adresse für Ihre Domain enthält.
• Kein gültiges Ticket. Führen Sie klist aus, um zu prüfen, ob ein gültiges Ticket vorhanden ist, oder führen Sie kinit aus, um eines zu erhalten.
• Keytab-Datei nicht gefunden. Überprüfen Sie den Pfad im Parameter krb5-keytabfile .

Weitere Informationen finden Sie unter SQL Server und Windows-Authentifizierung.

Fehler bei der Microsoft Entra ID-Authentifizierung

Fehlermeldung: clientCredentialFromCert: error reading certificate: ... oder DefaultAzureCredential: failed to acquire a token

Ursachen und Lösungen:

• Falsche Client-ID, Mieter-ID oder Client Secret. Überprüfe die Werte in der Verbindungszeichenfolge oder in den Umgebungsvariablen.
• Die verwaltete Identität ist nicht auf dem Host konfiguriert. Verifizieren Sie die Identität im Azure-Portal.
• Fehlender azuread Paketimport. Importiere github.com/microsoft/go-mssqldb/azuread und benutze den azuresql Treibernamen.

Weitere Informationen finden Sie unter Microsoft Entra ID-Authentifizierung.

Anmeldung fehlgeschlagen für Benutzer '' (leerer Benutzername)

Fehlermeldung: mssql: login error: Login failed for user ''.

Ursache: Sie haben sql.Open("sqlserver", ...) mit einem fedauth-Parameter verwendet. Die Entra ID-Authentifizierung erfordert den Treibernamen azuresql, der vom Paket azuread registriert wird. Beim Standardtreiber sqlserver wird der Parameter fedauth ignoriert und der Treiber versucht eine SQL-Authentifizierung ohne Benutzernamen.

Lösung: Importiere das azuread Paket und verwende den Treibernamen azuresql :

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

Weitere Informationen finden Sie unter Microsoft Entra ID-Authentifizierung.

Abfragefehler

Die folgenden Abschnitte behandeln Fehlermeldungen zur Abfrageausführung.

LastInsertId wird nicht unterstützt

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

Lösung: Der go-mssqldb Treiber unterstützt LastInsertId()nicht . Verwenden Sie eine OUTPUT Klausel oder eine separate Abfrage SCOPE_IDENTITY() .

Temporäre Tabelle nicht gefunden

Fehlermeldung: mssql: Invalid object name '#TempTable'.

Ursache: Temporäre Tabellen sind pro Verbindung. Wenn du in einem Aufruf eine temporäre Tabelle erstellst und sie in einem anderen abfragst, werden dafür möglicherweise unterschiedliche Verbindungen aus dem Pool verwendet.

Lösung: Verwenden Sie db.Conn(ctx), um die Verbindung auf eine einzelne Verbindung zu binden, oder führen Sie Operationen in einer Transaktion aus.

Weitere Informationen finden Sie unter "Gespeicherte Prozeduren".

Azure SQL-Fehler

Die folgenden Abschnitte behandeln Fehler, die spezifisch für die Azure SQL-Datenbank sind.

Fehlernummern bei vorübergehenden Verbindungsfehlern

Verwenden Sie die folgende gemeinsame Liste als Referenz für vorübergehende Verbindungsaufstellungsfehler und Anfrage-Pfad-Transportfehler, die für begrenzte Wiederholungen zugelassen sind:

Die folgenden Fehler sind vorübergehend, wenn sie während der Verbindungseinrichtung oder beim Senden einer Anforderung an den Server auftreten. Versuchen Sie es mit einem kurzen, begrenzten Backoff. Fehler, die über einige Wiederholungen bestehen, weisen in der Regel auf ein Konfigurationsproblem hin (falscher Server, fehlende Berechtigungen, erschöpftes Kontingent), das nicht behoben werden kann.

Fehler auf Anweisungsebene befinden sich nicht in dieser Liste, da sie ausgelöst werden, nachdem die Verbindung hergestellt wurde und der Fehler die Sitzung nutzbar lässt. Die häufigsten Fehler bei Anweisungen, die erneut ausgeführt werden können, sind 1205 (Deadlock-Opfer) und 1222 (Zeitüberschreitung bei der Sperranforderung). Wiederholen Sie die gesamte Transaktion statt der einzelnen fehlerhaften Anweisung.

Fehlermeldungstext stammt aus Azure SQL vorübergehenden Verbindungsfehlern. Einzelne Treiber verwalten ihre eigenen integrierten Wiederholungslisten; in diesem Katalog wird beschrieben, welche Fehler in SQL Server, Azure SQL-Datenbank, Azure SQL Managed Instance, SQL-Datenbank in Microsoft Fabric und dedizierten SQL-Pools in Azure Synapse Analytics für Wiederholungen geeignet sind.

Server kann nicht geöffnet werden (Firewall)

Fehlermeldung: 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.

Ursachen und Lösungen:

• Deine Client-IP ist nicht in den Azure SQL-Firewall-Regeln enthalten. Füge eine Firewall-Regel im Azure-Portal hinzu: SQL Server>Networking>Füge eine Firewall-Regel hinzu.
• Wenn Ihre Anwendung in Azure ausgeführt wird, aktivieren Sie Azure-Diensten und -Ressourcen den Zugriff auf diesen Server erlauben.
• Für die private Verbindung konfigurieren Sie einen privaten Endpunkt.

Ressourcenbeschränkung erreicht

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

Ursachen und Lösungen:

• Zu viele gleichzeitige Verbindungen für das Azure SQL-Tier. Senken Sie MaxOpenConns in Ihrer Pool-Konfiguration.
• Verbindungslecks (nicht abgeschlossene Zeilen oder Transaktionen). Überprüfe, ob defer rows.Close()- oder defer tx.Rollback()-Aufrufe fehlen.
• Mehrere Anwendungen teilen sich die Datenbank. Teilen Sie das Verbindungslimit auf alle Kunden auf.

Für Azure SQL-Verbindungsgrenzen nach Tier siehe Azure SQL-Datenbank.

Der Dienst ist derzeit ausgelastet (gedrosselt)

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

Ursachen und Lösungen:

• Die Datenbank steht unter hoher Überlastung. Implementieren Sie eine Logik für Wiederholungsversuche mit exponentiellem Backoff.
• Die Arbeitslast übersteigt die DTU- oder vCore-Kapazität der Stufe. Erwäge eine Hochskalierung.

Für Retry-Implementierungsmuster siehe Error Handling und Retry Patterns.

Datenbank derzeit nicht verfügbar

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

Ursache: Azure SQL konfiguriert die Datenbank neu (Failover-, Update- oder Skalierungsoperation). Diese Bedingung ist ein vorübergehender Fehler.

Lösung: Versuchen Sie die Operation erneut. Die Datenbank ist in der Regel innerhalb von Sekunden verfügbar. Weitere Informationen finden Sie unter Fehlerbehandlung und Wiederholungsmuster.

Schlechte Verbindungsfehler

Ein driver: bad connection Fehler bedeutet, dass der Treiber erkannt hat, dass eine bestehende Verbindung nicht mehr nutzbar ist. Der Pool database/sql versucht die Operation automatisch auf einer neuen Verbindung für nicht-transaktionale Aufrufe, aber Operationen innerhalb einer aktiven Transaktion schlagen sofort fehl.

Fang nicht mit diesem Abschnitt an, wenn die Anwendung nie erfolgreich verbunden wurde. driver: bad connection dies weist in der Regel auf die Wiederverwendung der Verbindung, Failover, Leerlauf-Timeout oder Netzwerkunterbrechungen hin, nachdem die erste Verbindung bereits funktionierte.

Häufige Ursachen

Wie Datenbank/SQL mit schlechten Verbindungen umgeht

Für Anrufe außerhalb einer Transaktion (db.QueryContext, db.ExecContext), versucht der Pool database/sql automatisch die Operation auf einer neuen Verbindung, wenn der Treiber eine fehlerhafte Verbindung meldet. Dieser Wiederholungsversuch ist für deinen Code transparent.

Für Aufrufe innerhalb einer Transaktion (tx.QueryContext, tx.ExecContext), kann der Pool nicht erneut versuchen, da der Transaktionszustand verloren geht. Dein Code muss den Fehler erkennen, zurückrollen und die gesamte Transaktion erneut versuchen.

Empfohlene Pool-Einstellungen für Azure SQL

Konfigurieren Sie den Pool so, dass er Azure-Gateway-Timeouts und Failovers verarbeitet:

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.

Bei lokal installiertem SQL Server ist ConnMaxIdleTime weniger kritisch, da es keine Leerlaufzeitüberschreitung des Gateways gibt. Die Aktivierung verhindert jedoch hängengebliebene Verbindungen bei Netzwerkunterbrechungen.

Für detaillierte Konfigurationsanleitungen siehe Azure SQL-Datenbank.

Erschöpfung des Pools

Pool-Erschöpfung tritt auf, wenn alle Verbindungen im Pool genutzt werden und neue Anrufer das Warten auf eine Verbindung blockieren.

Symptome

• Anfragen werden bei hoher Last langsamer oder es kommt zu Zeitüberschreitungen.
• db.Stats().WaitCount wächst kontinuierlich.
• db.Stats().InUse entspricht MaxOpenConns.
• Die Kontextfrist überschritt die Fehler während der Spitzenverkehrszeit.

Diagnose

Fügen Sie Ihrer Anwendung Poolüberwachung hinzu:

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)

Häufige Ursachen und Lösungen

Für detaillierte Hinweise zur Poolkonfiguration siehe Connection Pooling.

Langsame oder blockierte Abfragediagnostik

Abfrage-Timeouts festlegen

Nutzen Sie Kontextfristen, um langsame Abfragen zu identifizieren und zu verhindern, dass blockierte SQL-Aufrufe Verbindungen festnageln und Anrufer verzögern:

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

Für einen vollständigen Workflow zur Leistungsuntersuchung, einschließlich Abfragespeicher, DMVs, Analyse fehlender Indizes und Benchmarking, siehe Leistungsoptimierung.

Deadlock-Diagnostik

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

Fehlernummer: 1205

Lösung: In gleichzeitigen Systemen treten Deadlocks auf. Automatische Wiederholungslogik für Fehler 1205 implementieren. Für eine Deadlock-Wiederholungs-Wrapper-Funktion siehe Transaktionen.

Präventionsstrategien:

• Zugreifen Sie auf Tabellen in derselben Reihenfolge über alle Abfragen hinweg.
• Halten Sie Transaktionen kurz und vermeiden Sie die Interaktion der Nutzer während der Transaktionen.
• Verwenden Sie die READ COMMITTED SNAPSHOTisolation, um Sperrkonflikte zu reduzieren.

Wiederholte Deadlocks bei derselben Abfrage deuten auf ein Designproblem hin. Verwenden Sie den Deadlockgraphen (erfasst über Extended Events oder die Sitzung „system_health“), um die konkurrierenden Anweisungen und Sperrtypen zu ermitteln. Eine ausführliche Anleitung finden Sie im Deadlocks-Leitfaden. Für Deadlock-Handling-Strategien in Go siehe Deadlock-Handling und Handle Deadlocks.

Zertifikatsfehler bei Containern (Go 1.23 und spätere Versionen)

Fehlermeldung: x509: negative serial number

Ursache: Go 1.23 setzt RFC 5280 strikt durch. Das selbstsignierte Zertifikat, das SQL Server in Docker-Containern generiert, verwendet eine negative Seriennummer, die Go ablehnt.

Lösungen:

• Für Testumgebungen fügen Sie TrustServerCertificate=true hinzu, um die Zertifikatsvalidierung zu überspringen, oder encrypt=disable, um die Verschlüsselung vollständig zu deaktivieren.
• Für CI/CD setze die GODEBUG=x509negativeserial=1 Umgebungsvariable so, dass sie das Verhalten vor Go 1.23 wiederherstellt, ohne deine Verbindungszeichenfolge zu ändern.
• In go.mod (Go 1.23 und neueren Versionen) füge die Anweisung godebug x509negativeserial=1 hinzu, um die Überschreibung beim Build anzuwenden.

SHA-1-Zertifikatsfehler (Go 1.24 und neuere Versionen)

Fehlermeldung: tls: handshake failure Oder TLS Handshake failed: EOF beim Verbinden mit älteren SQL Server-Instanzen.

Ursache: Go 1.24 erlaubt standardmäßig keine SHA-1-Signaturalgorithmen in TLS-Zertifikaten. Ältere SQL Server-Versionen und einige On-Premises-Installationen verwenden Zertifikate, die mit SHA-1 signiert sind.

Lösungen:

• Stellen Sie das Serverzertifikat mit SHA-256 oder neuer (empfohlen) neu aus.
• Stellen Sie die GODEBUG=tlssha1=1 Umgebungsvariable so ein, dass sie SHA-1-Unterstützung vorübergehend wieder aktiviert.
• In go.mod (Go 1.23 und neueren Versionen) füge eine Direktive godebug tlssha1=1 hinzu.

Wann encrypt=disable bzw. TrustServerCertificate=true verwendet werden sollte

Weitere Informationen finden Sie unter Testing und Verschlüsselung sowie Zertifikate.

Kodierungs- und Sortierungsprobleme

Warnungen vor impliziter Umwandlung

Wenn Sie stringParameter (übergeben als nvarchar) an varcharSpalten übergeben, führt SQL Server eine implizite Konvertierung durch, die die Verwendung von Indizes verhindern kann.

Dieses Beispiel setzt das database/sql Setup mssql aus früheren Ausschnitten dieses Artikels fort.

Lösung: Verwendung mssql.VarChar für varchar Spalten:

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

CharsetToUTF8-Fehler mit nicht-lateinischen Zeichen

Fehlermeldung: CharsetToUTF8: ... beim Abfragen von varchar Spalten, die chinesische, japanische oder andere nicht-lateinische Zeichen enthalten, die in einer Kollation wie SQL_Latin1_General_CP1_CI_AS gespeichert sind.

Ursache: Der Treiber versucht, die Codepage der Spalte in UTF-8 umzuwandeln, aber die gespeicherten Bytes entsprechen nicht der erwarteten Kodierung der Kollation.

Lösungen:

• Verwenden nvarchar Sie statt varchar für Spalten, die nicht-lateinischen Text speichern. nvarchar Speichert Daten als UTF-16 und vermeidet Codepage-Konvertierung.
• Wenn du den Spaltentyp nicht ändern kannst, prüfe, ob die Datenbank-Sortierung den Zeichensatz unterstützt, den du speicherst.

Diagnoseprotokollierung aktivieren

Verwenden Sie den Verbindungsparameter log , um das Logging auf Treiberebene zu ermöglichen:

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

Log-Flags sind Bitmaskenwerte: 1 (Fehler), 2 (Nachrichten), 4 (Zeilen), 8 (SQL), 16 (Params), 32 (Transaktionen), 64 (Debugging). Kombinieren Sie Werte, indem Sie sie addieren (zum Beispiel 63 = alle außer Debug, 127 = alle).

Verwenden Sie für programmgesteuertes Logging SetLogger oder SetContextLogger. Siehe Protokollierung und Diagnose.

Checkliste zur Problembehandlung

Verwandte Inhalte

• Fehlerbehandlung und Wiederholungsmuster
• Verbindungspooling
• Azure SQL-Datenbank
• Transaktionen
• Protokollierung und Diagnose
• Bekannte Einschränkungen