Controlador ODBC de Microsoft para SQL Server

Descargar controlador ODBC

ODBC es la API nativa y principal de acceso a datos de las aplicaciones escritas en C y C++ para SQL Server. El controlador ODBC de Microsoft para SQL Server se conecta a SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics y la base de datos SQL en Microsoft Fabric. Para las versiones de base de datos que soporta cada versión de controlador, véase compatibilidad de versiones SQL.

Otros lenguajes que pueden usar ODBC incluyen COBOL, Perl, PHP y Python. ODBC se utiliza ampliamente en escenarios de integración de datos, y los controladores de Microsoft para PHP para SQL Server se basan en este controlador.

Las utilidades sqlcmd y bcp funcionan con este controlador, pero se instalan por separado: el mssql-tools18 paquete en Linux y macOS, y las utilidades de línea de comandos de Microsoft en Windows. Utiliza sqlcmd para ejecutar Transact-SQL sentencias (T-SQL), procedimientos de sistema y archivos de script. Usa bcp para copiar datos en masa entre una instancia de SQL Server y un archivo de datos, en cualquier dirección.

Elija el punto de partida.

• Para instalar el controlador, ve a Requisitos del sistema, archivos de instalación y controladores para Windows, o instala el controlador ODBC en Linux, instala el controlador ODBC en macOS e instala el gestor de controladores unixODBC.
• Para escribir tu primera aplicación, consulta Conectarse a una base de datos y consultarla con C++ y Palabras clave y atributos de DSN y de la cadena de conexión.
• Para conectarte a Azure SQL con autenticación sin contraseña, ve a Usar Microsoft Entra ID con el controlador ODBC.
• Para que una aplicación existente sea resistente a fallos transitorios, ve a Resiliencia de Conexión y Alta Disponibilidad y Recuperación ante Desastres.
• Para actualizar desde la versión 17, ve a Diferencias principales de versión y Solución de problemas de cifrado de conexión.
• Para diagnosticar un problema de conexión o consulta, ve a Resolución de problemas de cifrado de conexión y Problemas conocidos (Linux y macOS).

Línea base de producción para Azure SQL

Use este fragmento de código como punto de partida para una conexión Azure SQL orientada a producción. Carga el nombre del servidor y el nombre de la base de datos desde la configuración de la aplicación, se autentica con una identidad gestionada para que no aparezca ningún secreto en la cadena de conexión, y permite el cifrado Tabular Data Stream (TDS) 8.0 con validación completa del certificado. Establece un tiempo de espera para cada intento de inicio de sesión y reintenta la operación en caso de fallos transitorios con retroceso exponencial y variación aleatoria.

El fragmento de C++ de este artículo omite las directivas de inclusión, la asignación de identificadores y la función auxiliar de registro por motivos de brevedad.

std::wstring BuildConnectionString(const wchar_t* server, const wchar_t* database) {
    std::wstring cs = L"Driver={ODBC Driver 18 for SQL Server}";
    cs += L";Server=tcp:"; cs += server; cs += L",1433";
    cs += L";Database="; cs += database;
    cs += L";Authentication=ActiveDirectoryMsi";   // managed identity, no stored secret
    cs += L";Encrypt=strict";                      // TDS 8.0 with certificate validation
    cs += L";ConnectRetryCount=3";                 // idle connection resiliency, not initial connect
    cs += L";ConnectRetryInterval=10";
    return cs;
}

// Transient fault codes documented for Azure SQL, plus the resource governance
// codes. Network termination and timeout errors (64, 233, 258, 10053, 10054,
// 10060) are retried a bounded number of times, which is the documented
// guidance for them. 258 is the code the driver reports for a connect timeout.
// 10053 and 10054 can also mean the encryption handshake failed rather than a
// plain network reset, so read the error text before assuming a network fault.
bool IsTransient(SQLINTEGER nativeError) {
    switch (nativeError) {
        case 615: case 926: case 4060: case 4221:
        case 10928: case 10929: case 10936:
        case 40197: case 40501: case 40613:
        case 42108: case 42109:
        case 49918: case 49919: case 49920:
        case 40020: case 40143: case 40166: case 40540:   // failover subcodes
        case 64: case 233: case 258:
        case 10053: case 10054: case 10060:
            return true;
        default:
            return false;
    }
}

// Retries only errors that a new connection can clear, with exponential backoff
// plus jitter so that concurrent clients don't retry in lockstep.
SQLRETURN ConnectWithRetry(SQLHDBC hDbc, const std::wstring& connectionString, int maxAttempts) {
    SQLRETURN rc = SQL_ERROR;
    for (int attempt = 1; attempt <= maxAttempts; ++attempt) {
        // Set the per-attempt connect timeout through the connection attribute.
        // This works on every driver version, so the sample doesn't depend on
        // which connection string keywords a given release accepts.
        SQLSetConnectAttrW(hDbc, SQL_ATTR_LOGIN_TIMEOUT,
                           reinterpret_cast<SQLPOINTER>(static_cast<SQLLEN>(30)), 0);

        rc = SQLDriverConnectW(hDbc, nullptr,
                               const_cast<SQLWCHAR*>(reinterpret_cast<const SQLWCHAR*>(connectionString.c_str())),
                               SQL_NTS, nullptr, 0, nullptr, SQL_DRIVER_NOPROMPT);
        if (SQL_SUCCEEDED(rc)) {
            Log("INFO", "connected on attempt %d/%d", attempt, maxAttempts);
            return rc;
        }

        // Walks the diagnostic records and returns the first record that carries
        // a real SQL Server error number. Microsoft Entra failures report several
        // driver-specific records first, whose native error is 0.
        SQLINTEGER native = LogDiagnostics(SQL_HANDLE_DBC, hDbc, "connect");
        if (attempt == maxAttempts || !IsTransient(native)) return rc;

        // Cap the backoff at 64 seconds. This also keeps the shift in range
        // when a caller passes a large maxAttempts.
        int shift = (attempt - 1 < 6) ? attempt - 1 : 6;
        DWORD delayMs = (1UL << shift) * 1000UL + (DWORD)(GetTickCount64() % 500);
        Log("WARN", "retrying in %lu ms (attempt %d/%d)", delayMs, attempt + 1, maxAttempts);
        Sleep(delayMs);
    }
    return rc;
}

ConnectRetryCount y ConnectRetryInterval habilitan la resistencia de las conexiones inactivas, que restaura de forma transparente una conexión interrumpida durante la inactividad. No vuelven a intentar la conexión inicial, por eso este fragmento también implementa reintentos a nivel de aplicación. Conservar ambos.

ODBC proporciona diagnósticos a través de SQLGetDiagRec y no solo mediante el código de retorno, así que clasifica los errores antes de reintentar. Entonces, un error de autenticación o de configuración provoca un fallo inmediato en lugar de consumir todo el presupuesto total de reintentos.

Para obtener más información sobre cada parte de esta configuración, consulte:

• Palabras clave y atributos de DSN y de la cadena de conexión
• Utiliza Microsoft Entra ID con el controlador ODBC
• Solución de problemas de cifrado de conexión
• Resistencia de conexión
• Alta disponibilidad y recuperación ante desastres

Para el catálogo de errores transitorios de Azure SQL, véase códigos de error de fallo transitorio.

Características clave

• Multiplataforma: La misma API en Windows, Linux y macOS.
• Autenticación Microsoft Entra ID: Conexiones sin contraseña con identidad gestionada, principal de servicio, flujos interactivos e integrados.
• Cifrado estricto: conexiones TDS 8.0 con validación completa de certificados en la versión 18 y versiones posteriores.
• Always Encrypted: Cifrado en el lado del cliente para columnas sensibles, con soporte para proveedores de tiendas de claves personalizadas.
• Resiliencia de la conexión: Restauración transparente de una conexión que se cayó mientras estaba en reposo.
• Alta disponibilidad: Disponibilidad del grupo de soporte para oyentes con MultiSubnetFailover.
• Clasificación de datos: Metadatos de sensibilidad para columnas clasificadas.
• Tipo de dato vectorial: Soporte nativo para el tipo vectorial .
• Transacciones distribuidas: soporte para transacciones XA a través del Coordinador de transacciones distribuidas de Microsoft (MSDTC).
• Herramientas complementarias: sqlcmd y bcp, instalados por separado.

Empieza ahora

Instalación del controlador

Configuración y conexión

Autenticar y asegurar

Alta disponibilidad y resistencia

Trabajar con datos

Diagnóstico y solución de problemas

Notas de lanzamiento y correcciones de errores

Reference

Contenido relacionado

• Referencia del Programador ODBC: La especificación de la API ODBC que implementa este controlador, documentada por separado del controlador.
• Características de SQL Server Native Client: El comportamiento del controlador está documentado únicamente en el contenido nativo del Cliente. Estos artículos se aplican al controlador ODBC para SQL Server, excepto donde describan OLE DB.
• Utilidad BCP: La utilidad de copia masiva, instalada por separado del controlador.
• Utilidad SQLCMD: La utilidad de consulta de línea de comandos, instalada por separado del controlador.
• Matriz de compatibilidad de funciones del controlador
• Blog de controladores de SQL Server