Cet article répond aux questions courantes concernant l’installation, la connexion et le développement d’applications pour le pilote Microsoft ODBC pour SQL Server sur Linux et macOS.
À propos du pilote
Quelle version de pilote ODBC devrais-je utiliser ?
Utilisez le pilote ODBC 18 de Microsoft pour SQL Server, la ligne de pilotes actuelle, pour le nouveau développement. Le pilote Microsoft ODBC 17 pour SQL Server reste pris en charge pour les applications qui le déploient déjà, comme décrit dans le cycle de vie de support.
Le changement de mise à niveau qui affecte la plupart des applications est que Driver 18 chiffre les connexions par défaut. Pour toutes les différences, voir Différences de versions majeures.
Quels systèmes d’exploitation et architectures de processeurs le pilote prend-il en charge ?
Le pilote 18 prend en charge, ces systèmes d’exploitation et architectures de processeurs :
| Système d'exploitation | Prise en charge x64 | Prise en charge d’Arm64 |
|---|---|---|
| Alpine Linux | Yes | À partir du Driver 18.3 |
| Azure Linux | Yes | À partir du pilote 18.6.1 |
| Debian | Yes | À partir du Driver 18.1 |
| Oracle Linux | Yes | No |
| Red Hat Enterprise Linux | Yes | À partir du pilote 18.1 |
| SUSE Linux Enterprise Server | Yes | No |
| Ubuntu | Yes | À partir du Driver 18.1 |
| macOS | Yes | À partir du Driver 17.8 |
Les versions du système d’exploitation prises en charge changent à chaque sortie de pilote. Pour le tableau version par version, voir Exigences système.
Quelles fonctionnalités de SQL Server le pilote Linux et macOS supporte-t-il ?
Le pilote sous Linux et macOS prend en charge la plupart des fonctionnalités de SQL Server. Il ne prend pas en charge l’enrôlement dans une transaction distribuée via l’attribut SQL_ATTR_ENLIST_IN_DTC, la mise en miroir de bases de données, FILESTREAM ou les attributs de profilage des performances du pilote. LocalDB n’est pas disponible sur Linux ou macOS. Les transactions XA via le Distributed Transaction Coordinator (DTC) sont prises en charge à partir du pilote 17.3. Pour plus d’informations, voir Utiliser les transactions XA avec DTC. Pour la liste complète, voir Limitations.
Le pilote est-il open source ?
No. Le pilote Microsoft ODBC pour SQL Server n'est pas open source.
Installation et configuration
Quel gestionnaire de pilotes ODBC le pilote utilise-t-il ?
Le pilote utilise le gestionnaire de pilotes unixODBC. Lorsque vous installez le pilote 17 ou 18 avec le gestionnaire de paquets ou Homebrew de votre plateforme, unixODBC s’installe en tant que dépendance. Suivez les étapes pour Linux ou macOS.
Sur macOS, créez et exécutez votre application avec unixODBC plutôt qu’iODBC. Faites correspondre l’architecture processeur de l’application, du gestionnaire de pilotes et du pilote. Une erreur comme incompatible architecture (have 'arm64', need 'x86_64') indique un décalage d’architecture, pas nécessairement le mauvais gestionnaire de pilotes.
Comment puis-je vérifier quels pilotes sont installés et quels fichiers de configuration sont utilisés ?
Exécutez odbcinst -q -d pour afficher la liste des pilotes enregistrés. La sortie affiche chaque nom de pilote exactement comme une chaîne de connexion doit l’écrire :
[ODBC Driver 18 for SQL Server]
Exécutez odbcinst -j pour afficher la version unixODBC et les chemins de odbcinst.ini, qui enregistre les pilotes, et odbc.ini, qui contient les noms des sources de données système et utilisateur (DSN) :
unixODBC 2.3.11
DRIVERS............: /etc/odbcinst.ini
SYSTEM DATA SOURCES: /etc/odbc.ini
FILE DATA SOURCES..: /etc/ODBCDataSources
USER DATA SOURCES..: /home/<user>/.odbc.ini
Pour configurer un DSN, voir Chaînes de connexion et DSN.
Pourquoi le gestionnaire de pilotes signale-t-il qu’il ne peut pas ouvrir la bibliothèque de pilotes ?
L’erreur ressemble à ceci :
[01000][unixODBC][Driver Manager]Can't open lib 'ODBC Driver 18 for SQL Server' : file not found
Vérifiez ces causes dans l’ordre :
- La valeur
Driverdans la chaîne de connexion ou le DSN ne correspond pas au nom du pilote enregistré. Exécutezodbcinst -q -det copiez le nom à l’identique. - Votre application utilise des fichiers de configuration différents de ceux que vous avez modifiés. Exécutez
odbcinst -jdepuis le même environnement que l’application et vérifiez quel gestionnaire de pilotes l’application charge. Sur macOS, créez des liens symboliques de configuration uniquement si l’application en a besoin, comme décrit dans Dépannage sur macOS. - Plus d’une copie du gestionnaire de pilotes unixODBC est installée, et votre application charge le mauvais gestionnaire. Sur Linux, exécutez
find /usr -name 'libodbc*.so*'. Sur macOS, exécutezfind /opt/homebrew /usr/local -name 'libodbc*.dylib'. Plusieurs chemins seuls ne prouvent pas que plusieurs gestionnaires de pilotes/drivers sont installés : les liens Homebrew peuvent pointer vers la même bibliothèque dans son répertoire Cellar. Vérifiez quelle bibliothèque l’application charge réellement. Pour plus d’informations, voir Résoudre les problèmes de connexion.
Se connecter et s’authentifier
Pourquoi une connexion qui fonctionne avec le pilote 17 échoue-t-elle avec une erreur de certificat sur le pilote 18 ?
Le pilote 18 est défini par défaut sur Encrypt=yes. Le pilote 17 se règle par défaut sur Encrypt=no uniquement lorsqu’aucun paramètre Authentication non vide ou jeton d’accès n’est fourni. Un paramètre non vide Authentication, incluant Authentication=SqlPassword, ou un jeton d’accès modifie la valeur par défaut du pilote 17 en Encrypt=yes. Des paramètres de chiffrement explicites remplacent ces paramètres par défaut.
Vérifiez les paramètres effectifs dans votre chaîne de connexion, DSN et attributs de préconnexion définis via SQLSetConnectAttr. Par exemple, Encrypt=yes dans un DSN ou SQL_COPT_SS_ENCRYPT=SQL_EN_ON demande le chiffrement même lorsque la chaîne de connexion omet Encrypt. Fournir les jetons d’accès uniquement via l’attribut de connexion SQL_COPT_SS_ACCESS_TOKEN, et non via un mot-clé de chaîne de connexion.
Avec Encrypt=yes et TrustServerCertificate=no, les deux pilotes chiffrent la connexion et valident le certificat serveur. Avec Encrypt=no, le pilote 17 ne valide pas le certificat, tandis que le pilote 18 le valide si le serveur force le chiffrement et TrustServerCertificate=no. Une connexion qui utilisait auparavant le Driver 17 Encrypt=no par défaut peut donc échouer avec le Driver 18 contre un serveur disposant d’un certificat auto-signé ou autrement non fiable. Avec un certificat auto-signé, l’erreur du Driver 18 ressemble à ceci :
[Microsoft][ODBC Driver 18 for SQL Server]SSL Provider: [error:0A000086:SSL routines::certificate verify failed:self-signed certificate]
[Microsoft][ODBC Driver 18 for SQL Server]Client unable to establish connection. For solutions related to encryption errors, see https://go.microsoft.com/fwlink/?linkid=2226722
Privilégiez un certificat approuvé ou un épinglage de certificat. Utilisez ces options :
- Installez un certificat sur le serveur émis par une autorité de certification en qui le client a confiance. Si le certificat est fiable mais que son nom ne correspond pas à la valeur
Server, il faut définirHostNameInCertificatesur le nom figurant dans le certificat.HostNameInCertificatene change que le nom attendu, donc cela ne corrige pas un certificat auto-signé. - Avec le pilote 18.1 et les versions ultérieures, ainsi qu’un serveur prenant en charge le Tabular Data Stream (TDS) 8.0, il faut définir
Encrypt=strictetServerCertificatesur le chemin d’une copie du certificat du serveur. Le pilote accepte alors uniquement ce certificat exact.ServerCertificatefonctionne uniquement en mode strict. - Définissez
Encrypt=noseulement si vous acceptez le trafic applicatif non chiffré lorsque le serveur ne force pas le chiffrement. Cela correspond à la valeur par défaut du pilote 17 uniquement lorsqu’aucun réglage non videAuthenticationou jeton d’accès n’est fourni et qu’aucun surcontrôle de chiffrement n’est activé. Si le serveur force le chiffrement, le pilote 18 valide toujours le certificat sauf siTrustServerCertificate=yesdésactive la validation.
Caution
TrustServerCertificate=yes n’active pas le chiffrement. Avec Encrypt=yes, il contourne la validation des certificats tout en maintenant le trafic chiffré, laissant la connexion ouverte aux attaques d’adversaire dans le milieu (adversary-in-the-middle). Avec Encrypt=no, le trafic applicatif reste non chiffré sauf si le serveur force le chiffrement ; si le serveur force le chiffrement, la validation du certificat est contournée. Avec Encrypt=strict, le pilote ignore TrustServerCertificate et valide le certificat, ou le compare à ServerCertificate lorsqu'il est configuré. Privilégiez un certificat de confiance ou un épinglage de certificat.
Pour plus d’informations, voir Comportement de chiffrement par défaut.
Le pilote supporte-t-il l’authentification Kerberos ?
Oui. Obtenez un ticket Kerberos avec kinit, puis connectez-vous avec Trusted_Connection=yes dans la chaîne de connexion ou le DSN. L’instance SQL Server nécessite un nom de principal de service (SPN) enregistré. Pour les étapes de configuration, voir Utiliser l’authentification intégrée.
Le pilote supporte-t-il l’authentification Microsoft Entra ID ?
Oui, pour Azure SQL Database, Azure SQL Managed Instance, et SQL Server 2022 et versions ultérieures. Pour configurer SQL Server, y compris via Azure Arc, utilisez l’authentification Microsoft Entra pour SQL Server. Sous Linux et macOS, Driver 17 et les versions ultérieures prennent en charge ces méthodes :
- Identité managée, avec
Authentication=ActiveDirectoryMsi, à partir du pilote 17.3. - Service principal, avec
Authentication=ActiveDirectoryServicePrincipal, à partir de Driver 17.7. - Authentification intégrée via Kerberos dans un environnement fédéré, avec
Authentication=ActiveDirectoryIntegrated, à partir du pilote 17.6. - Un jeton d’accès que votre application obtient, transmis via l’attribut de connexion
SQL_COPT_SS_ACCESS_TOKEN.
ActiveDirectoryInteractiveest disponible uniquement dans le pilote Windows.
ActiveDirectoryPassword est obsolète. L’authentification gérée par les pilotes sur Linux et macOS ne prend pas en charge les scénarios nécessitant des politiques d’accès conditionnelles. Si votre application acquiert un jeton d’accès séparément, la bibliothèque d’authentification et les politiques Microsoft Entra ID régissent cette acquisition de jeton. Faites passer le jeton via SQL_COPT_SS_ACCESS_TOKEN.
Sur Alpine Linux, l’authentification intégrée nécessite une libcurl compilation prenant en charge le mécanisme de négociation SPNEGO (Simple and Protected Generic Security Service Application Program Interface Negotiation Mechanism). Vérifiez vos capacités installées libcurl plutôt que de supposer que le package par défaut les supporte.
Pour les chaînes de connexion et les exemples de code, voir Utiliser Microsoft Entra ID avec le pilote ODBC.
Développer et dépanner
Une application ODBC existante peut-elle utiliser le pilote sous Linux ou macOS ?
Oui. Une application écrite pour l’interface de programmation d’applications ODBC (API) et compilée avec unixODBC peut charger ce pilote. Pour utiliser des fonctionnalités spécifiques à SQL Server, incluez msodbcsql.h après les en-têtes unixODBC. Pour les commandes de compilateur et les noms de bibliothèque, voir Développer des applications C et C++ avec le pilote ODBC.
Existe-t-il un exemple d’application ?
Oui. Se connecter et interroger avec C++ et ODBC permet de compiler et d’exécuter un exemple sur Linux, macOS et Windows.
Comment puis-je tracer les appels ODBC ?
Les fichiers trace peuvent contenir des données sensibles. Avec le compte qui exécute votre application, créez un répertoire auquel seul ce compte peut accéder :
mkdir -m 700 "$HOME/odbc-trace"
Ajoutez ces paramètres dans la section [ODBC] de odbcinst.ini. Remplacez /home/<user>/odbc-trace/odbctrace.log par le chemin absolu à l’intérieur du répertoire que vous avez créé. Sur macOS, les répertoires personnels utilisent /Users/<user> généralement au lieu de /home/<user>.
Gardez le chemin complet du fichier de trace à 62 octets ou moins pour éviter la troncature par unixODBC.
[ODBC]
Trace = Yes
TraceFile = /home/<user>/odbc-trace/odbctrace.log
Ces réglages permettent le traçage pour les applications utilisant cette configuration de gestionnaire de pilotes, et le traçage les ralentit. Utilisez un répertoire privé distinct pour chaque compte applicatif. Supprimez Trace = Yes quand vous avez terminé, et supprimez les fichiers de trace dont vous n’avez plus besoin. Pour le traçage par application, voir Traçage d’accès aux données sous Linux et macOS.
Données de caractères
Quel encodage Unicode une application devrait-elle utiliser ?
Utilisez UTF-16LE (little endian) pour les SQLWCHAR données. Utilisez des tampons UTF-16 SQLWCHAR avec les API ODBC à caractères larges au lieu du type natif wchar_t , qui est de 32 bits sous Linux et macOS.
Utilisez UTF-8 pour les données SQLCHAR. À partir du pilote 17, le pilote accepte également un ensemble de pages de codes d’un et de deux octets pour les données SQLCHAR lorsque le paramètre régional du processus en sélectionne une. Les processus commencent dans la C locale, donc le pilote utilise UTF-8 sauf si l’application appelle setlocale. Pour la liste des encodages, voir Gérer les données de caractères.