Pilote Microsoft ODBC pour SQL Server

Télécharger le pilote ODBC

ODBC est l’API d’accès aux données native principale pour les applications écrites en C et en C++ pour SQL Server. Le pilote Microsoft ODBC pour SQL Server se connecte à SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics et la base de données SQL dans Microsoft Fabric. Pour les versions de base de données prises en charge par chaque version de pilote, voir compatibilité avec SQL.

Les autres langages qui peuvent utiliser ODBC incluent COBOL, Perl, PHP et Python. ODBC est largement utilisé dans les scénarios d’intégration de données, et les pilotes Microsoft pour PHP pour SQL Server sont construits sur ce pilote.

Les utilitaires sqlcmd et bcp fonctionnent avec ce pilote, mais ils s’installent séparément : le mssql-tools18 paquet sous Linux et macOS, et les utilitaires en ligne de commande Microsoft sur Windows. Utilisez sqlcmd pour exécuter Transact-SQL instructions (T-SQL), procédures système et fichiers script. Utilisez BCP pour copier en masse des données entre une instance de SQL Server et un fichier de données, dans les deux sens.

Choisir votre point de départ

Base de référence de production pour Azure SQL

Utilisez cet extrait de code comme point de départ pour une connexion Azure SQL orientée production. Il charge le nom du serveur et celui de la base de données depuis la configuration de l’application, s’authentifie avec une identité gérée afin qu’aucun secret n’apparaisse dans la chaîne de connexion, et active le chiffrement Tabular Data Stream (TDS) 8.0 avec validation complète des certificats. Il définit un délai d’expiration pour chaque tentative de connexion et réessaie les échecs transitoires avec une temporisation exponentielle et une variation aléatoire.

L’extrait C++ de cet article omet inclure, gérer l’allocation et l’aide à journalisation pour plus de concision.

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 et ConnectRetryInterval activer la résilience des connexions inactives, ce qui restaure de manière transparente une connexion coupée pendant l’inactivité. Ils ne réessaient pas la connexion initiale, c’est pourquoi ce fragment implémente aussi une réessayage au niveau de l’application. Gardez les deux.

ODBC rapporte les diagnostics par l’intermédiaire de SQLGetDiagRec plutôt qu’au seul moyen du code de retour ; classez donc les échecs avant toute nouvelle tentative. Une erreur d’authentification ou de configuration échoue alors immédiatement au lieu de consommer tout le budget de réessayage.

Pour plus d’informations sur chaque partie de cette configuration, consultez :

Pour le catalogue des erreurs transitoires Azure SQL, voir codes d’erreur de défaut transitoire.

Principales fonctionnalités

  • Multiplateforme : La même API sur Windows, Linux et macOS.
  • Authentification Microsoft Entra ID : Connexions sans mot de passe avec identité managée, principal de service, flux interactifs et intégrés.
  • Chiffrement strict : connexions TDS 8.0 avec validation complète des certificats dans la version 18 et les versions ultérieures.
  • Always Encrypted : Chiffrement côté client pour les colonnes sensibles, avec prise en charge des fournisseurs de magasins de clés personnalisés.
  • Résilience de la connexion : Restauration transparente d’une connexion qui a été coupée alors qu’elle était inactive.
  • Haute disponibilité : Support des auditeurs du groupe de disponibilité avec MultiSubnetFailover.
  • Classification des données : Métadonnées de sensibilité pour les colonnes classifiées.
  • Type de données vectorielles : support natif du type de vecteur .
  • Transactions distribuées : prise en charge des transactions XA via le Microsoft Distributed Transaction Coordinator (MSDTC).
  • Outils compagnons : sqlcmd et bcp, installés séparément.

Get started

Article Description
Télécharger un pilote ODBC pour SQL Server Installateurs et téléchargements de paquets pour toutes les versions de pilotes prises en charge, sur les trois plateformes.
Connectez-vous et interrogez une base de données en C++ Un échantillon complet en C++ qui connecte, lance une requête et lit les résultats, afin que vous puissiez confirmer votre installation de bout en bout.
Cycle de vie de support Quelles versions de pilotes sont encore prises en charge, et à quelle date chacune cesse de l’être.
Différences entre les versions principales Qu’est-ce qui casse quand on passe de la version 17 à la version 18, en commençant par le changement par défaut du chiffrement ?

Installer le pilote

Article Description
Exigences système, installations et fichiers de pilotes (Windows) Versions Windows prises en charge, la ligne de commande d’installateur pour le déploiement silencieux, et où chaque fichier pilote atterrit sur le disque.
Exigences système (Linux et macOS) Les distributions Linux et les versions de macOS prises en charge par chaque version du pilote, ainsi que la compatibilité avec les versions de SQL Server.
Installer le pilote ODBC sur Linux Étapes du gestionnaire de paquets pour Alpine, Debian, Red Hat, SUSE, Ubuntu et Azure Linux, ainsi que l’installation hors ligne et les emplacements des fichiers des pilotes.
Installer le pilote ODBC sur macOS Étapes relatives au tap Homebrew et à la formule pour macOS, y compris la procédure d’installation des versions 18, 17 ou 13.1.
Installer le gestionnaire de pilotes unixODBC (Linux et macOS) Installez ou mettez à jour unixODBC, le gestionnaire de pilotes qui charge le pilote ODBC sur Linux et macOS.

Configuration et connexion

Article Description
DSN et mots-clés et attributs de chaîne de connexion Le catalogue complet des mots-clés de chaîne de connexion, des entrées DSN et des attributs SQLSetConnectAttr, avec les valeurs acceptées pour chacun d’eux.
Mots-clés de chaînes de connexion et noms de sources de données (Linux et macOS) Comment définir un DSN sur Linux et macOS à l’aide de odbc.ini et odbcinst.ini, ainsi que les paramètres TLS et TCP de maintien de connexion propres à ces plateformes.
Administrateur de la source de données ODBC DSN (Windows) Chaque option dans les pages de l’assistant DSN Windows, lorsque vous configurez une source de données via l’interface utilisateur plutôt qu’à l’aide d’une chaîne de connexion.
Pool de connexions adapté au pilote (Windows) Quels mots-clés et attributs de la chaîne de connexion placent une connexion dans son propre pool, et lesquels nécessitent un aller-retour supplémentaire pour la réinitialiser.

Authentifier et être sécurisé

Article Description
Utilisez Microsoft Entra ID avec le pilote ODBC Chaque Authentication valeur de mot-clé, de l’identité gérée et du principal de service à l’interactif et intégré, avec la configuration dont chacun a besoin.
Utilisez Always Encrypted avec le pilote ODBC Chiffrer les colonnes sensibles dans le processus client afin que le texte en clair n’atteigne jamais le serveur, avec le résumé de l’API du pilote et ses limitations documentées.
Classification des données Lisez les étiquettes de sensibilité que le serveur attache aux colonnes classifiées, afin que votre application puisse appliquer sa propre politique de protection des données.
Utilisez l’authentification intégrée (Linux et macOS) Configurez Kerberos pour qu’un client Linux ou macOS puisse se connecter avec des identifiants Windows au lieu d’une connexion SQL Server.

Haute disponibilité et résilience

Article Description
Résilience des connexions Comment ConnectRetryCount et ConnectRetryInterval rétablissent une connexion lorsque le serveur l’interrompt alors qu’elle est inactive, et les erreurs IMCxx que le pilote renvoie quand la récupération est impossible.
Haute disponibilité et récupération d’urgence Connectez-vous à l’aide d’un écouteur de groupe de disponibilité et utilisez MultiSubnetFailover pour éviter que le basculement ne soit retardé en cas de délai d’expiration du sous-réseau.
Utiliser une résolution IP réseau transparente Comment le mécanisme de repli historique TransparentNetworkIPResolution organise les tentatives de connexion entre plusieurs adresses IP, et pourquoi MultiSubnetFailover le remplace avantageusement.

Utiliser des données

Article Description
Type de données vectorielles Associez, envoyez et récupérez le type vector, y compris sa représentation native en C et la prise en charge de la copie en bloc.
Utiliser les transactions XA avec DTC Engagez SQL Server dans une transaction distribuée via le Microsoft Distributed Transaction Coordinator sur Windows, Linux ou macOS.
Directives de programmation (Linux et macOS) Quelles fonctionnalités le pilote prend en charge sous Linux et macOS, lesquelles il ne prend pas en charge, et en quoi la gestion des jeux de caractères et d’OpenSSL diffère de celle de Windows.

Diagnostiquer et résoudre les problèmes

Article Description
Dépannage du chiffrement des connexions Corrigez les erreurs de certificat et de chiffrement que la version 18 met en avant car elle chiffre par défaut.
Traçage des accès aux données (Linux et macOS) Activez la recherche des conducteurs et capturez un fichier journal lorsque vous avez besoin de voir les appels que votre application effectue réellement.
Problèmes connus (Linux et macOS) Défauts confirmés et leurs solutions de contournement. Vérifiez ici avant de déposer une demande de soutien.
Foire aux questions (Linux et macOS) Des réponses courtes aux questions qui reviennent le plus souvent sur le pilote sous Linux et macOS.

Notes de publication et corrections de bugs

Article Description
Notes de version pour Windows Nouvelles fonctionnalités, changements de comportement et correctifs à chaque version du pilote Windows.
Notes de version pour Linux et macOS Nouvelles fonctionnalités, changements de comportement et corrections dans chaque version des pilotes Linux et macOS.
Notes de version pour les outils SQL Server Modifications apportées aux utilitaires sqlcmd et bcp , qui s’installent séparément du pilote sur Linux et macOS.

Reference

Article Description
Pilote ODBC sous Windows Un résumé version par version de ce que le pilote supporte sous Windows, ainsi qu’un index des articles spécifiques à Windows.
Fonctionnalités du pilote ODBC sur Windows Quelle version a introduit chaque fonctionnalité Windows, ainsi que les changements de comportement qui l’accompagnaient.

Contenu connexe

  • Last updated on