Dépannage des problèmes d’installation et de connexion avec mssql-python

Utilisez cet article pour diagnostiquer les problèmes d’installation, de connexion, de conteneur et d’intégration continue (CI) avec le mssql-python pilote.

Problèmes d’installation

pip échoue à l’installation ou compile à partir du code source

Symptômes :

error: Microsoft Visual C++ 14.0 or greater is required
ERROR: Failed building wheel for mssql-python

Causes et solutions possibles :

  • Pas de volant préassemblé pour votre plateforme

    • Vérifiez que vous utilisez une version Python prise en charge (versions 3.10 et ultérieures) et une plateforme. Voir cycle de vie du support pour la matrice de compatibilité.
    • Mettez à jour le pip avant l’installation avec pip install --upgrade pip.
    • Pour les environnements d’équipe reproductibles, utilisez le flux de travail verrouillé dans les déploiements répétables ou les patrons de conteneurs dans le contenu et le développement local afin de réduire la dérive locale des machines.

  • Environnement virtuel non activé

    • Activez d’abord votre environnement virtuel. L’installation de Python dans le système peut entraîner des erreurs ou des conflits de permissions.
    python -m venv .venv
.venv\Scripts\activate
pip install mssql-python

Installations de pilotes en conflit

Symptômes :

Vous rencontrez des erreurs d’importation ou des comportements inattendus après l’installation mssql-python et pyodbc dans le même environnement.

Solution:

mssql-python et pyodbc peuvent coexister. Si vous rencontrez des conflits, créez un environnement virtuel propre.

python -m venv .venv --clear
.venv\Scripts\activate
pip install mssql-python

Problèmes de connexion

Impossible de se connecter au serveur

Symptômes :

OperationalError: [08001] (0) Client unable to establish connection

Causes et solutions possibles :

  • Serveur injoignable

    • Vérifiez que le nom du serveur et le port sont corrects.
    • Vérifiez la connectivité réseau avec ping <server> ou telnet <server> 1433.
    • Assurez-vous que le pare-feu autorise les connexions sortantes sur le port 1433.

  • SQL Server ne fonctionne pas

    • Vérifiez que le service SQL Server est bien lancé.
    • Pour les instances nommées, vérifiez que le service SQL Server Browser fonctionne.

  • Règles de pare-feu Azure SQL

    • Ajoutez votre adresse IP client aux règles du pare-feu Azure SQL dans le portail Azure.
    • Pour Azure SQL Managed Instance, assurez-vous de vous connecter depuis un réseau autorisé.

Tester la connectivité TCP de base :

import socket

try:
    sock = socket.create_connection(("<server>.database.windows.net", 1433), timeout=5)
    print("TCP connection successful")
    sock.close()
except Exception as e:
    print(f"Cannot reach server: {e}")

Échec de la connexion

Symptômes :

OperationalError: [28000] (18456) Login failed for user '<user_id>'.

Causes et solutions possibles :

  • Non-correspondance du mode d’authentification

    • Pour Azure SQL Database, Azure SQL Managed Instance et SQL Database dans Fabric, il faut privilégier un mode Microsoft Entra tel que Authentication=ActiveDirectoryDefault.
    • Si vous utilisez intentionnellement l’authentification SQL, vérifiez que le serveur le permet et que vous utilisez le bon format de connexion pour ce point de terminaison.

  • Identifiants d’authentification SQL incorrects

    • Vérifiez l’identifiant utilisateur et le mot de passe.
    • Pour Azure SQL, incluez l’identifiant utilisateur complet : <user_id>@<server>.

  • L’utilisateur n’existe pas dans la base de données

    • Vérifiez que l’utilisateur a accès à la base de données spécifiée.
    • Vérifiez si la connexion est associée à un utilisateur de la base de données.

  • Authentification non configurée

    • Utilisez l’authentification Microsoft Entra (recommandée) : Authentication=ActiveDirectoryDefault.
    • Si vous dépannez une instance locale de SQL Server qui devrait accepter l’authentification SQL, vérifiez que SQL Server utilise l’authentification en mode mixte.

Délai d’expiration de la connexion

Symptômes :

OperationalError: [HYT00] (0) Timeout expired
OperationalError: [HYT01] (0) Connection timeout expired

Causes et solutions possibles :

  • Le serveur répond lentement

    • Augmentez le délai d’attente de la connexion.
    conn = mssql_python.connect(connection_string, timeout=60)

  • Latence du réseau

    • Vérifie le chemin réseau vers le serveur.
    • Considérons un chemin réseau plus court ou un réseau privé virtuel (VPN).

  • Serveur sous forte charge

    • Essayez de vous connecter pendant les heures creuses.
    • Contactez votre administrateur de base de données.

Erreurs de certificat SSL

Symptômes :

OperationalError: [08001] SSL Provider: The certificate chain was issued by an authority that is not trusted

Solutions :

Privilégiez un certificat de confiance ou les schémas de développement local dans Container et le développement local. Utilisez-les TrustServerCertificate=yes uniquement pour le développement local sur un serveur que vous contrôlez.

Pour le développement et les tests avec un certificat auto-signé :

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
    "TrustServerCertificate=yes;"  # Don't use in production
)

Caution

TrustServerCertificate=yes est une solution de secours uniquement locale. Ne le transportez pas dans des conteneurs de développement partagés, des pipelines CI ou des déploiements en production. Pour plus d’informations, voir Chiffrement et certificats.

Pour la production, installez les certificats appropriés et utilisez :

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
    "HostnameInCertificate=<server>.domain.com;"
)

Problèmes liés aux conteneurs et à la CI

Bibliothèques système manquantes sur Linux

Symptômes :

ImportError: libltdl.so.7: cannot open shared object file: No such file or directory
ImportError: libkrb5.so.3: cannot open shared object file

Solution:

Installez les packages système nécessaires pour votre distribution :

Distribution Commande d'installation
Ubuntu ou Debian sudo apt-get install libltdl7 libkrb5-3 libgssapi-krb5-2
Red Hat ou Fedora sudo dnf install libtool-ltdl krb5-libs
Alpine apk add libltdl krb5-libs

Pour des exemples de Dockerfile, voir Conteneur et développement local.

Erreurs SSL de macOS après installation

Symptômes :

Vous rencontrez des erreurs liées à SSL lorsque vous vous connectez depuis macOS, surtout sur Apple Silicon.

Solution:

Installez OpenSSL avec Homebrew, et définissez les drapeaux de liaison :

brew install openssl
export LDFLAGS="-L/opt/homebrew/opt/openssl/lib"
export CPPFLAGS="-I/opt/homebrew/opt/openssl/include"

Contenu connexe

  • Last updated on