Usa go-mssqldb con Azure SQL Database

El go-mssqldb controlador soporta la conexión a Azure SQL Database, Azure SQL Managed Instance y base de datos SQL en Microsoft Fabric. Este artículo trata sobre la configuración, autenticación, límites de conexión y resolución de problemas específicas de Azure que difieren de SQL Server local.

Conectarse a Azure SQL Database

Azure SQL Database requiere conexiones cifradas por defecto. Especifica encrypt=true y TrustServerCertificate=false explícitamente para que la conexión use TLS y valide el certificado del servidor:

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

Note

Cuando omites encrypt, el controlador no añade automáticamente la configuración TLS específica de Azure. Mantén encrypt=true&TrustServerCertificate=false en las cadenas de conexión de Azure SQL.

Utiliza autenticación sin contraseña (recomendada)

La autenticación de Microsoft Entra ID elimina contraseñas de tus cadenas de conexión. ActiveDirectoryDefault selecciona automáticamente la mejor credencial disponible para el entorno, lo que facilita el desarrollo:

import (
    "database/sql"
    "log"

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

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

Importante

ActiveDirectoryDefault es conveniente para el desarrollo, pero puede añadir latencia de conexión porque sondea múltiples fuentes de credenciales. Para servicios de producción, prefiera un método explícito como ActiveDirectoryManagedIdentity o ActiveDirectoryServicePrincipal.

Cómo ActiveDirectoryDefault resuelve las credenciales

ActiveDirectoryDefault prueba las siguientes fuentes de credenciales en orden y utiliza la primera que tenga éxito:

Pedido	Fuente de credenciales	Entorno típico
1	Variables de entorno (`AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`)	Canalizaciones CI/CD, contenedores Docker
2	Identidad de la carga de trabajo	Pods de Kubernetes con Azure Workload Identity
3	Identidad administrada	Azure VMs, App Service, Container Apps, Azure Functions
4	CLI de Azure (`az login`)	Desarrollo local
5	CLI para desarrolladores de Azure (`azd auth login`)	Desarrollo local

Esta cadena de credenciales hace que ActiveDirectoryDefault resulte conveniente durante el desarrollo, pero el sondeo secuencial añade latencia a cada nueva conexión. Para producción, especifique el método exacto de autenticación (como ActiveDirectoryManagedIdentity) para que el controlador se salte comprobaciones innecesarias.

Identidad gestionada para producción (recomendado)

Las aplicaciones alojadas en Azure (App Service, Container Apps, Azure Functions o Azure VMs) deben usar una identidad gestionada con un valor explícitofedauth. Este enfoque evita la sobrecarga de la cadena de credenciales y elimina cualquier dependencia de variables de entorno o del estado de la CLI.

Identidad administrada asignada por el sistema:

sqlserver://<server>.database.windows.net?database=<database>&fedauth=ActiveDirectoryManagedIdentity&encrypt=true&TrustServerCertificate=false

Identidad gestionada asignada por el usuario (especificar el ID del cliente):

sqlserver://<server>.database.windows.net?database=<database>&fedauth=ActiveDirectoryManagedIdentity&user id=<client-id>&encrypt=true&TrustServerCertificate=false

Concede acceso a la identidad en la base de datos

Después de configurar la identidad gestionada en el recurso de Azure, crea un usuario de base de datos contenido:

CREATE USER [my-app-identity] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [my-app-identity];
ALTER ROLE db_datawriter ADD MEMBER [my-app-identity];

Para las identidades asignadas por el sistema, utiliza el nombre del recurso Azure. Para las identidades asignadas por el usuario, usa el nombre de identidad.

Principio de servicio para automatización

Para canalizaciones CI/CD o autenticación servicio-a-servicio:

sqlserver://<server>.database.windows.net?database=<database>&fedauth=ActiveDirectoryServicePrincipal&user id=<client-id>&password=<client-secret>&encrypt=true&TrustServerCertificate=false

Para todos los tipos de credenciales, consulte autenticación Microsoft Entra ID.

Configurar el cortafuegos de Azure

Azure SQL Database utiliza un cortafuegos a nivel de servidor. Debes permitir la dirección IP pública de tu cliente o usar un endpoint privado.

Error: No se puede abrir el servidor

Este mensaje de error indica que el firewall de Azure está bloqueando la dirección IP de tu cliente:

mssql: login error: Cannot open server '<server>' requested by the login.
Client with IP address '<client-ip>' is not allowed to access the server.

Soluciones:

Añadir una regla de firewall en el portal de Azure: SQL Server>Networking>Añadir una regla de firewall.
Activa Permitir que los servicios y recursos de Azure accedan a este servidor si tu aplicación se ejecuta en Azure.
Para la conectividad privada, configura un punto final privado.

Error: La conexión se agotó

Si la conexión se apaga sin un error claro, es probable que el cortafuegos esté bloqueando la conexión de forma silenciosa. Verifica primero las reglas del cortafuegos.

Límites de conexión por nivel de servicio

Azure SQL Database aplica límites de conexión por base de datos según el nivel de servicio. Superar el límite provoca fallos de autenticación para nuevas conexiones. Para las tablas completas de límites, véase límites de recurso único de base de datos DTU y límites de recurso único de base de datos vCore.

Configura MaxOpenConns para que coincidan con tu nivel

Siempre establece MaxOpenConns un valor por debajo del límite de conexión para tu nivel Azure SQL:

// Example for S2 tier (60 max workers).
// Leave headroom for Azure management connections and other clients.
db.SetMaxOpenConns(20)
db.SetMaxIdleConns(10)
db.SetConnMaxLifetime(5 * time.Minute)

Tip

Si varias aplicaciones comparten la misma base de datos, divide el límite de conexión entre todas las aplicaciones. Por ejemplo, si tres servicios comparten una base de datos S2 (60 trabajadores máximo), asigna entre 15 y 20 conexiones por servicio.

Administrar la limitación de Azure SQL

Azure SQL Database puede limitar conexiones y consultas cuando la base de datos se acerque a los límites de recursos (CPU, IO, memoria o número de sesiones). La limitación se manifiesta mediante determinados códigos de error.

Errores comunes de limitación de velocidad

Número de error	Patrón de mensaje	Causa
10928	`Resource ID: %d. The %s limit for the database is %d and has been reached.`	Se ha alcanzado el límite de sesión o de trabajadores.
10929	`Resource ID: %d. The %s minimum guarantee is %d, maximum limit is %d.`	Limitación del regulador de recursos.
40501	`The service is currently busy.`	Limitación de velocidad general vuelva a intentarlo.
40544	`The database has reached its size quota.`	Límite de tamaño de base de datos alcanzado. Aumente la capacidad o el espacio libre antes de volver a intentarlo.
40549	`Session is terminated because you have a long-running transaction.`	La transacción superó el límite de tiempo.
40550	`Session is terminated because of too many locks.`	Adquisición excesiva de bloqueos.
40551	`Session is terminated because of excessive tempdb usage.`	Uso excesivo de tempdb.
40552	`Session is terminated because of excessive transaction log usage.`	El espacio de registro de transacciones se ha excedido.
40553	`Session is terminated because of excessive memory usage.`	Consumo excesivo de memoria.
40613	`Database '%.ls' on server '%.ls' is not currently available.`	Base de datos que se mueve o se reconfigura.
49918	`Cannot process request. Not enough resources to process request.`	Agotamiento de recursos.
49919	`Cannot process create or update request.`	Demasiadas operaciones concurrentes de creación/actualización.
49920	`Cannot process request. Too many operations in progress.`	Límite de operación concurrente alcanzado.

Solicitudes de reintentos con limitación

La mayoría de los errores de limitación y disponibilidad de Azure SQL en la tabla anterior son transitorios y deben intentarse de nuevo con retroceso exponencial. El error 40544 no es transitorio. Significa que la base de datos ha alcanzado su cuota de tamaño, así que la operación no tendrá éxito hasta que escales la base de datos o elimines datos.

Para una implementación completa de reintentos, consulte Gestión de errores y patrones de reintentos.

import (
    "errors"

    mssql "github.com/microsoft/go-mssqldb"
)

func isAzureThrottling(err error) bool {
    var mssqlErr mssql.Error
    if !errors.As(err, &mssqlErr) {
        return false
    }
    switch mssqlErr.Number {
    case 10928, 10929, 40501, 40549, 40550, 40551, 40552, 40553,
        40613, 49918, 49919, 49920:
        return true
    }
    return false
}

Resistencia de la conexión

Azure SQL Database ocasionalmente reconfigura servidores para actualizaciones, conmutaciones por error y balanceo de carga. Estos eventos interrumpen las conexiones existentes, lo que se muestra como errores driver: bad connection. Configura tu pool para que se recupere automáticamente:

db.SetConnMaxLifetime(5 * time.Minute)  // Rotate connections so stale ones are replaced.
db.SetConnMaxIdleTime(2 * time.Minute)  // Recycle before Azure gateway drops idle connections (30 min).
db.SetMaxIdleConns(10)                  // Keep warm connections for quick recovery.

Note

La pasarela Azure SQL cierra conexiones que están inactivas durante unos 30 minutos. Establece ConnMaxIdleTime muy por debajo de este umbral para evitar driver: bad connection errores en la primera consulta tras un periodo de inactividad. Para las llamadas no transaccionales, database/sql vuelve a intentarlo automáticamente con una nueva conexión. Para las llamadas transaccionales, tu código debe detectar el error y volver a intentar toda la transacción.

Reconexión tras la conmutación por error

Fuera de las transacciones, database/sql puede reintentar de forma transparente una llamada iniciada sobre una conexión defectuosa cuando el controlador marca la conexión como inutilizable. Este comportamiento no constituye una directiva completa de reintento para errores transitorios en casos de limitación, conmutación por error u otros errores SQL reintentables. Envuelve tus llamadas a la base de datos en una función de reintento para manejar esos escenarios:

var count int
err := RetryFunc(ctx, DefaultRetryConfig, func(ctx context.Context) error {
    return db.QueryRowContext(ctx, "SELECT COUNT(*) FROM HumanResources.Employee").Scan(&count)
})

Consulta Patrones de gestión de errores y reintentos para implementar RetryFunc.

Instancia Gestionada de Azure SQL

Azure SQL Managed Instance soporta las mismas funciones de controladores que el SQL Server local, con algunas diferencias:

Feature	Azure SQL Database	Instancia Gestionada de Azure SQL
Agente de SQL Server	No disponible	Available
Consultas entre bases de datos	No disponible	Available
Servidores vinculados	No disponible	Available
Canalizaciones con nombre	No disponible	No disponible (solo TCP)
Memoria compartida	No disponible	No disponible (solo TCP)
Autenticación de Windows (SSPI)	No disponible	Disponible dentro de la VNet gestionada

Conectarse a una instancia administrada:

sqlserver://<user>:<password>@<instance>.database.windows.net?database=<database>&encrypt=true&TrustServerCertificate=false

Base de datos SQL en Microsoft Fabric