Solucionar el problema del controlador go-mssqldb

Este artículo ofrece soluciones para errores comunes y problemas de conectividad con el go-mssqldb controlador.

Empieza con las comprobaciones más sencillas

Antes de activar el registro detallado o cambiar la configuración del grupo, consulta la siguiente lista:

  1. Verifica la accesibilidad básica: nombre del servidor, puerto, reglas del firewall y si SQL Server o Azure SQL acepta conexiones.
  2. Verifica las entradas de autenticación: nombre del driver, nombre de usuario, contraseña, formato de dominio o fedauth configuración.
  3. Verifica la configuración de TLS: encrypt, rutas de certificado, hostnameincertificate, y si TrustServerCertificate es apropiado para el entorno.
  4. Solo cuando la configuración de la conexión sea correcta, investigue el agotamiento del conjunto de conexiones, las conexiones obsoletas, la lógica de reintentos y el diagnóstico de consultas lentas o bloqueadas.

Utiliza las primeras secciones de este artículo para fallos en la configuración de conexiones. Usa las secciones siguientes solo después de que las conexiones se establezcan correctamente al menos algunas veces y luego fallen bajo carga, tras un periodo de inactividad o durante la conmutación por error.

Errores de conexión

Las siguientes secciones cubren los mensajes de error comunes relacionados con la conexión y sus soluciones.

No se puede abrir la conexión TCP

Mensaje de error: 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.

Causas y soluciones:

  • SQL Server no está funcionando. Inicie el servicio SQL Server.
  • TCP/IP no está habilitado. Abre Administrador de configuración de SQL Server y activa TCP/IP bajo SQL Server Network Configuration>Protocols.
  • Puerto equivocado. Verifica el puerto en Administrador de configuración de SQL Server o utiliza SQL Server Browser para instancias con nombre.
  • El cortafuegos está bloqueando el puerto. Añade una regla de entrada para el puerto 1433 (o para tu puerto configurado).

Error de inicio de sesión para el usuario

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

Causas y soluciones:

  • Nombre de usuario o contraseña incorrectos. Verifica las credenciales.
  • La autenticación de SQL Server está desactivada. Activa SQL Server y el modo de autenticación de Windows en las propiedades del servidor.
  • El inicio de sesión no existe. Crea el inicio de sesión en SQL Server.
  • El usuario no tiene acceso a la base de datos de destino. Concede acceso a bases de datos con CREATE USER.

Errores de validación de certificados

Mensaje de error: TLS Handshake failed: x509: certificate signed by unknown authority

Causas y soluciones:

  • El servidor utiliza un certificado auto-firmado. Proporciona la ruta del certificado con el certificate parámetro o serverCertificate , o configúrala TrustServerCertificate=true solo para desarrollo.
  • El certificado de CA no está en la tienda de confianza del sistema. Añade el certificado de la CA al almacén de confianza del sistema operativo o especifícalo con el certificate parámetro.
  • El nombre de host no coincide. Úsalo hostnameincertificate para especificar el nombre esperado en el certificado.

Para más información, véase Cifrado y certificados.

Se ha agotado el tiempo de espera de la conexión.

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

Causas y soluciones:

  • Problemas de conectividad de red. Verifica que puedes acceder al servidor usando telnet <server> 1433 o Test-NetConnection -ComputerName <server> -Port 1433.
  • Fallo en la resolución DNS. Verifica que el nombre de host se resuelva correctamente.
  • Aumente dial timeout o connection timeout en la cadena de conexión.

Errores de autenticación

Las siguientes secciones cubren los mensajes de error de autenticación.

Fallos de autenticación NTLM

Mensaje de error: NTLM authentication failed

Causas y soluciones:

  • Formato de dominio incorrecto. Úsalo DOMAIN\user en el user id parámetro. En formato URL, codifica la barra inversa como %5C.
  • Contraseña incorrecta. Verifica la contraseña del dominio.

Errores de autenticación Kerberos

Mensaje de error: krb5: cannot resolve KDC for realm

Causas y soluciones:

  • Faltan elementos o están mal configurados /etc/krb5.conf. Verifica que la [realms] sección contenga la dirección KDC correcta para tu dominio.
  • No hay ningún tique válido. Corre klist a comprobar si tienes un ticket válido, o corre kinit a conseguirlo.
  • Archivo de teclado no encontrado. Verifica la ruta en el krb5-keytabfile parámetro.

Para más información, consulta SQL Server y autenticación de Windows.

Fallos de autenticación de Microsoft Entra ID

Mensaje de error: clientCredentialFromCert: error reading certificate: ... o DefaultAzureCredential: failed to acquire a token

Causas y soluciones:

  • ID de cliente, ID del inquilino o el secreto del cliente incorrectos. Verifica los valores en la cadena de conexión o en las variables de entorno.
  • La identidad gestionada no está configurada en el host. Verifica la identidad en el portal de Azure.
  • Falta la importación del paquete azuread. Importa github.com/microsoft/go-mssqldb/azuread y usa el nombre del controlador azuresql.

Para obtener más información, consulte Autenticación de Id. de Microsoft Entra.

Inicio de sesión fallido para el usuario '' (nombre de usuario vacío)

Mensaje de error: mssql: login error: Login failed for user ''.

Causa: Usaste sql.Open("sqlserver", ...) con un fedauth parámetro. La autenticación de Entra ID requiere el nombre del controlador azuresql registrado por el paquete azuread. Con el controlador estándar sqlserver , el fedauth parámetro se ignora y el controlador intenta autenticación SQL sin nombre de usuario.

Solución: Importar el azuread paquete y usar el nombre del azuresql controlador:

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

Para obtener más información, consulte Autenticación de Id. de Microsoft Entra.

Errores de consulta

Las siguientes secciones cubren los mensajes de error de ejecución de consultas.

LastInsertId no soportado

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

Solución: El go-mssqldb controlador no soporta LastInsertId(). Usa una cláusula OUTPUT o una consulta SCOPE_IDENTITY() por separado.

Tabla temporal no encontrada

Mensaje de error: mssql: Invalid object name '#TempTable'.

Causa: Las tablas temporales son específicas de cada conexión. Si creas una tabla temporal en una llamada y la consultas en otra, podrían usar diferentes conexiones del pool.

Solución: Use db.Conn(ctx) para fijar a una única conexión, o agrupe las operaciones en una transacción.

Para obtener más información, consulte Procedimientos almacenados.

Errores de Azure SQL

Las siguientes secciones cubren errores específicos de Azure SQL Database.

Números de error de conexión transitoria

Utiliza la siguiente lista compartida como referencia para errores transitorios en el establecimiento de conexión y fallos de transporte en la ruta de solicitud que sean elegibles para reintentos acotados:

Los errores siguientes son transitorios cuando se producen durante el establecimiento de la conexión o al enviar una solicitud al servidor. Vuelva a intentarlo en un retroceso corto y limitado. Los errores que persisten más allá de algunos reintentos suelen indicar un problema de configuración (servidor incorrecto, permisos que faltan, cuota agotada) que el reintento no corregirá.

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.) La conexión TCP se interrumpe a mitad del establecimiento de conexión. No es un fallo de credenciales. Si persiste, compruebe si hay inestabilidad en la red del cliente o algún dispositivo intermedio que interrumpa conexiones establecidas solo parcialmente.
233 The client was unable to establish a connection because of an error during connection initialization process before login. Error de transporte antes del inicio de sesión o de TLS. Normalmente, el servidor lo devuelve cuando no puede aceptar la conexión (agotamiento de recursos, conexiones máximas alcanzadas o un cliente no admitido). No es un fallo de credenciales. Compruebe el estado del servidor y, a continuación, compruebe el tiempo de espera de inicio de sesión del cliente, la configuración de TLS y la compatibilidad de la versión de TLS de cliente/servidor.
4060 Cannot open database "%.*ls" requested by the login. The login failed. El inicio de sesión se autentica, pero no puede abrir la base de datos solicitada. Las causas transitorias incluyen que la base de datos está en transición (conmutación por error, restauración, escalado) o pausada automáticamente. Las causas persistentes (la base de datos no existe, el inicio de sesión no tiene acceso) no se corregirán reintentando; compruebe el nombre de la base de datos, la asociación del inicio de sesión y el estado de la base de datos.
4221 Login to read-secondary failed due to long wait on 'HADR_DATABASE_WAIT_FOR_TRANSITION_TO_VERSIONING'. La réplica no está disponible para el inicio de sesión porque faltan versiones de fila para las transacciones que estaban en curso cuando se reciclaba la réplica. Revierta o confirme las transacciones activas en el servidor principal para resolver el problema. Mitíguelo evitando transacciones de escritura prolongadas en la base de datos principal.
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.) El extremo local interrumpe la conexión. Compruebe el estado de la red del lado cliente y cualquier firewall local o cliente VPN.
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.) El extremo remoto envía un reinicio de TCP. Causas comunes: el proceso remoto se bloqueó, un firewall forzó un restablecimiento de la conexión o la puerta de enlace de Azure SQL cerró una conexión inactiva. Para los patrones de reinicio por inactividad, habilite TCP keepalive en el cliente o reduzca el tiempo de espera de inactividad del pool de conexiones.
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. La base de datos supera un límite de gobernanza de recursos Azure SQL. El identificador de recurso 1 indica el límite de trabajo; El identificador de recurso 2 indica el límite de sesión. Identifique el tipo de límite a partir del mensaje y reduzca la concurrencia, amplíe la base de datos o acorte las operaciones de larga duración que mantienen el recurso.
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. La base de datos supera su garantía mínima y el servidor subyacente está limitando. Normalmente, el reintento suele tener éxito cuando disminuye la carga de los vecinos. Las apariciones sostenidas indican que necesita un nivel de servicio superior o un entorno menos ruidoso.
40020, 40143, , 40166, 40540 Se informó de la ranura Error code %d del error 40197 durante la conmutación por error. Subcódigos incrustados en un mensaje de conmutación por error 40197 que algunas rutas muestran como número de error principal. Tratarlos igual que 40197.
40197 The service has encountered an error processing your request. Please try again. Error code %d. Una actualización de software, un error de hardware u otro evento de conmutación por error en Azure SQL. Al volver a conectarse, se le dirige a una réplica en buen estado. El código de error integrado identifica el tipo de conmutación por error. Si el error persiste, capture el identificador de seguimiento de sesión y póngase en contacto con el soporte técnico.
40501 The service is currently busy. Retry the request after 10 seconds. Incident ID: %ls. Code: %d. Limitación del motor de Azure SQL. El tiempo de espera mínimo recomendado es de 10 segundos. El estrangulamiento sostenido indica que la carga de trabajo ha superado la asignación de recursos de la base de datos; aumente el nivel de servicio o reduzca la concurrencia.
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'. La base de datos no está disponible, normalmente durante una conmutación por error o brevemente durante una operación de escalado. Reintentar tras un tiempo de espera progresivo; si el problema persiste más de unos minutos, capturar el ID de seguimiento de la sesión y abrir un caso de soporte.
42108 Can not connect to the SQL pool since it is paused. Please resume the SQL pool and try again. El grupo de SQL dedicado (Synapse) está en un estado en pausa. El reintento solo tiene éxito después de que se reanude la agrupación. Reanude explícitamente el grupo o programe la carga de trabajo para que se ejecute después de reanudar el grupo.
42109 The SQL pool is warming up. Please try again. El grupo de SQL dedicado se está reactivando. Vuelva a intentarlo con un intervalo de espera creciente hasta que el pool esté en línea; el calentamiento suele tardar unos minutos.
49918 Cannot process request. Not enough resources to process request. The service is currently busy. Please retry the request later. El servidor no puede asignar recursos suficientes actualmente para satisfacer la solicitud. Vuelva a intentarlo después de un tiempo de espera. Si el error persiste, aumente la capacidad de la base de datos o del grupo elástico.
49919 Cannot process create or update request. Too many create or update operations in progress for subscription "%ld". Límite de concurrencia a nivel de suscripción en las operaciones de administración. Reduzca las llamadas de creación y actualización paralelas o escalonelas.
49920 Cannot process request. Too many operations in progress for subscription "%ld". Límite de concurrencia a nivel de suscripción para las operaciones en ejecución. Reduzca el paralelismo o espere a que finalicen las operaciones en curso.

Los errores a nivel de instrucción no están en esta lista porque se producen después de que se haya establecido la conexión y el fallo no impide seguir usando la sesión. Los errores de instrucciones que se pueden reintentar más comunes son 1205 (víctima de interbloqueo) y 1222 (tiempo de espera de la solicitud de bloqueo). Reintente la transacción completa en lugar de la sola instrucción que falla.

El texto del mensaje de error procede de Azure SQL errores de conexión transitorios. Los controladores individuales mantienen sus propias listas integradas de reintentos; este catálogo describe qué errores son susceptibles de reintento en SQL Server, Azure SQL Database, Azure SQL Managed Instance, la base de datos SQL de Microsoft Fabric y los grupos dedicados de SQL en Azure Synapse Analytics.

No se puede abrir el servidor (cortafuegos)

Mensaje de error: 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.

Causas y soluciones:

  • La IP de tu cliente no está en las reglas del firewall de Azure SQL. Añadir una regla de firewall en el portal de Azure: SQL Server>Networking>Añadir una regla de firewall.
  • Si tu aplicación se ejecuta en Azure, activa Permitir que los servicios y recursos de Azure accedan a este servidor.
  • Para la conectividad privada, configura un punto final privado.

Límite de recursos alcanzado

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

Causas y soluciones:

  • Demasiadas conexiones concurrentes para el nivel Azure SQL. Reduce MaxOpenConns en la configuración de tu pool.
  • Fugas de conexión (filas o transacciones sin cerrar). Comprueba si faltan las llamadas defer rows.Close() o defer tx.Rollback().
  • Múltiples aplicaciones compartiendo la base de datos. Divide el límite de conexión entre todos los clientes.

Para los límites de conexión de Azure SQL por nivel, consulta Azure SQL Database.

El servicio está ocupado en este momento (limitación de velocidad)

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

Causas y soluciones:

  • La base de datos está bajo una carga pesada. Implemente lógica de reintentos con retroceso exponencial.
  • La carga de trabajo supera la capacidad de DTU o de vCore del nivel. Considera ampliar la capacidad.

Para patrones de implementación de reintentos, véase Gestión de errores y patrones de reintento.

Base de datos no disponible actualmente

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

Causa: Azure SQL está reconfigurando la base de datos (conmutación por error, actualización o escalado). Esta condición es un error transitorio.

Solución: Intenta de nuevo la operación. La base de datos suele estar disponible en cuestión de segundos. Para más información, consulte Gestión de errores y patrones de reintento.

Errores de conexión defectuosa

Un error significa que el controlador detectó driver: bad connection que una conexión existente ya no es utilizable. El database/sql grupo vuelve a intentar la operación automáticamente con una conexión nueva para las llamadas no transaccionales, pero las operaciones dentro de una transacción activa fallan inmediatamente.

No empieces con esta sección si la aplicación nunca se conectó con éxito. driver: bad connection Normalmente apunta a reutilización de conexión, conmutación por error, tiempo de espera o interrupciones de red después de que la conexión inicial ya estuviera funcionando.

Causas comunes

Causa Escenario típico Corregir
Tiempo de espera por inactividad de la puerta de enlace de Azure SQL Conexión inactiva durante 30+ minutos detrás del gateway de Azure. Configura db.SetConnMaxIdleTime(2 * time.Minute) para reciclar conexiones inactivas antes de que la pasarela las abandone.
Interrupción de la red Fallo transitorio de la red entre el cliente y el servidor. Implementa lógica de reintentos para operaciones no transaccionales. Consulta Manejo de errores.
Finalización de sesión en el servidor El DBA canceló la sesión o el servidor se reinició. vuelva a intentarlo. Configura db.SetConnMaxLifetime para rotar las conexiones.
Reconfiguración de Azure SQL Un evento de conmutación por error, escalado o aplicación de parches interrumpió la conexión. Configura ConnMaxLifetime a 5 minutos o menos. Implemente la lógica de reintento.
Tiempo de espera de transacción de larga duración Azure SQL terminó la sesión (error 40549). Mantén las transacciones cortas. Divida las operaciones grandes en lotes más pequeños.

Cómo gestionan las malas conexiones en bases de datos/SQL

Para llamadas fuera de una transacción (db.QueryContext, db.ExecContext), el grupo database/sql reintenta automáticamente la operación en una nueva conexión cuando el controlador informa de una conexión errónea. Este reintento es transparente para tu código.

Para llamadas dentro de una transacción (tx.QueryContext, tx.ExecContext), el pool no puede volver a intentarlo porque se pierde el estado de la transacción. Tu código debe detectar el error, revertir y volver a intentar toda la transacción.

Configura el pool para gestionar los tiempos de espera y conmutaciones por error de la puerta de enlace de 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.

En implementaciones locales de SQL Server, ConnMaxIdleTime es menos crítico porque no hay tiempo de espera por inactividad de la puerta de enlace. Sin embargo, configurarlo evita conexiones obsoletas tras interrupciones de red.

Para una guía detallada de configuración, consulte Azure SQL Database.

Agotamiento en la piscina

El agotamiento de la piscina ocurre cuando todas las conexiones están en uso y los nuevos llamantes bloquean la espera de una conexión.

Síntomas

  • Las peticiones se ralentizan o expiran bajo carga.
  • db.Stats().WaitCount crece continuamente.
  • db.Stats().InUse es igual a MaxOpenConns.
  • El plazo de contexto superaba los errores durante el tráfico pico.

Diagnóstico

Añade monitorización de pools a tu aplicación:

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)

Causas habituales y sus soluciones

Causa Cómo identificarlo Corregir
rows.Close() no se ha llamado InUse crece con el tiempo, nunca disminuye. Añade defer rows.Close() después de cada QueryContext.
Transacciones de larga duración InUse permanece en un nivel alto durante el procesamiento por lotes. Mantén las transacciones cortas. Procesa lotes grandes en trozos más pequeños.
MaxOpenConns demasiado bajo WaitCount crece de forma constante bajo carga normal después de descartar recursos atrapados y fugas. Aumente MaxOpenConns.
MaxOpenConns no establecido Cientos de conexiones abiertas con carga pico. Efíjate MaxOpenConns en un valor acotado.
Fuga de goroutines al llamar a db.Conn InUse crece sin el correspondiente aumento de solicitudes. Asegúrate de que cada db.Conn() resultado esté cerrado con defer conn.Close().

Para obtener una guía detallada sobre la configuración de la agrupación, consulte Agrupación de conexiones.

Diagnósticos de consultas lentas o bloqueadas

Establecer tiempos de espera de consulta

Utiliza los plazos contextuales para identificar consultas lentas y evitar que las llamadas SQL bloqueadas bloqueen conexiones y retrasen a los llamantes:

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

Para un flujo de trabajo completo de investigación de rendimiento, incluyendo Almacén de consultas, DMVs, análisis de índices faltantes y benchmarking, consulte Ajuste de rendimiento.

Diagnósticos de interbloqueo

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

Número de error: 1205

Solución: Los bloqueos ocurren en sistemas concurrentes. Implementa lógica de reintento automático para el error 1205. Para una función contenedora de reintento en caso de interbloqueo, véase Transacciones.

Estrategias de prevención:

  • Accede a las tablas en el mismo orden en todas las consultas.
  • Mantén las transacciones cortas y evita la interacción del usuario durante las operaciones.
  • Utilice el aislamiento READ COMMITTED SNAPSHOT para reducir la contención de bloqueos.

Los bloqueos repetidos en la misma consulta indican un problema de diseño. Utiliza el gráfico de bloqueo (capturado mediante Eventos Extendidos o la sesión de salud del sistema) para identificar las sentencias y tipos de bloqueo en competencia. Para una guía completa, consulta la guía de Deadlocks. Para consultar estrategias de gestión de interbloqueos en Go, consulte Gestión de interbloqueos y Gestionar interbloqueos.

Errores de certificados con contenedores (Go 1.23 y versiones posteriores)

Mensaje de error: x509: negative serial number

Causa: Go 1.23 aplica estrictamente la RFC 5280. El certificado autofirmado que SQL Server genera en contenedores Docker usa un número de serie negativo, que Go rechaza.

Soluciones:

  • Para entornos de prueba, añade TrustServerCertificate=true para saltar la validación de certificados o encrypt=disable desactivar el cifrado por completo.
  • Para CI/CD, configura la GODEBUG=x509negativeserial=1 variable de entorno para restaurar el comportamiento previo a Go 1.23 sin cambiar tu cadena de conexión.
  • En go.mod (Go 1.23 y versiones posteriores), añade una directiva godebug x509negativeserial=1 para aplicar la sobrescritura en tiempo de compilación.

Precaución

No uses TrustServerCertificate=true ni encrypt=disable en producción. Estas opciones desactivan las comprobaciones de seguridad. Para producción, utiliza un certificado debidamente firmado.

Errores de certificados SHA-1 (Go 1.24 y versiones posteriores)

Mensaje de error: tls: handshake failure o TLS Handshake failed: EOF al conectar a instancias antiguas de SQL Server.

Causa: Go 1.24 no permite por defecto algoritmos de firma SHA-1 en los certificados TLS. Las versiones anteriores de SQL Server y algunas instalaciones locales utilizan certificados firmados con SHA-1.

Soluciones:

  • Reemite el certificado del servidor con SHA-256 o posterior (recomendado).
  • Configura la GODEBUG=tlssha1=1 variable de entorno para que reactive temporalmente el soporte SHA-1.
  • En go.mod (Go 1.23 y versiones posteriores), añade la directiva godebug tlssha1=1.

Cuándo usar encrypt=disable frente a TrustServerCertificate=true

Configuración Qué hace Cuándo se deben usar
TrustServerCertificate=true Cifra el tráfico pero omite la validación del certificado. Desarrollo local y pruebas donde el servidor utiliza un certificado autofirmado.
encrypt=disable Envía tráfico en texto plano (sin TLS). Entornos heredados donde TLS no está disponible. No se recomienda.
encrypt=strict TDS 8.0 con validación TLS completa desde el primer byte. Producción en SQL Server 2022 o Azure SQL.

Para más información, véase Pruebas y Cifrado y certificados.

Problemas de codificación y cotelación

Advertencias de conversión implícitas

Si pasas string parámetros (enviados como nvarchar) a varchar columnas, SQL Server realiza una conversión implícita que puede impedir el uso del índice.

Este ejemplo continúa la configuración de database/sql y mssql a partir de fragmentos anteriores de este artículo.

Solución: Uso mssql.VarChar para varchar columnas:

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

Error CharsetToUTF8 con caracteres no latinos

Mensaje de error: CharsetToUTF8: ... al consultar varchar columnas que contienen caracteres chinos, japoneses u otros caracteres no latinos almacenados en una colación como SQL_Latin1_General_CP1_CI_AS.

Causa: El controlador intenta convertir la página de códigos de la columna a UTF-8, pero los bytes almacenados no coinciden con la codificación esperada de la colación.

Soluciones:

  • Úsalo nvarchar en lugar de varchar para columnas que almacenan texto no latino. nvarchar almacena los datos como UTF-16 y evita la conversión de páginas de códigos.
  • Si no puedes cambiar el tipo de columna, verifica que la clasificación de la base de datos soporte el conjunto de caracteres que estás almacenando.

Habilitación del registro de diagnóstico

Utiliza el parámetro de conexión log para habilitar el registro a nivel de controlador:

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

Las banderas de registro son valores de máscara de bits: 1 (errores), 2 (mensajes), 4 (filas), 8 (SQL), 16 (parámetros), 32 (transacciones), 64 (depuración). Combina valores sumándolos (por ejemplo, 63 = todos excepto depuración, 127 = todos).

Para el registro programático, utiliza SetLogger o SetContextLogger. Consulte Registro y diagnóstico.

Lista de comprobación para la solución de problemas

Síntoma Primer paso
Conexión rechazada Verifica que SQL Server está funcionando y TCP/IP está habilitado.
Error de inicio de sesión Revisa las credenciales y el modo de autenticación.
Error de certificado Comprueba el certificado del servidor o establece TrustServerCertificate=true (solo para desarrollo).
Tiempo de espera de conexión Verifica la ruta de red con Test-NetConnection. Compruebe las reglas de firewall.
Firewall de Azure SQL Añade tu IP a las reglas del firewall de Azure SQL.
Errores de limitación de velocidad Implementa retry con retroceso exponencial. Escala el nivel.
Mala conexión Configura ConnMaxIdleTime en menos de 30 minutos para Azure SQL. Implemente la lógica de reintento.
Agotamiento en la piscina Supervisar db.Stats(). Corregir filas/transacciones no cerradas. Aumente MaxOpenConns.
Consultas lentas Establece tiempos de espera contextuales. Consulta las DMV para identificar las consultas costosas.
Interbloqueos Implementar reintento en caso de error 1205. Accede a las tablas en un orden consistente.
Conversión implícita Usa mssql.VarChar para las columnas varchar.

Contenido relacionado

  • Last updated on