Sélectionnez le pilote de base de données mssql-django

À partir de la version 2.0, mssql-django il se connecte via l’un des deux pilotes de base de données Python :

  • pyodbc avec un pilote Microsoft ODBC installé externement pour SQL Server. Ce pilote est le par défaut.
  • mssql-python, le pilote Python de Microsoft, qui n'a pas besoin d'un pilote ODBC installé séparément.

Vous choisissez le pilote pour chaque alias de base de données. Un alias peut être utilisé mssql-python pendant que le reste du projet reste actif pyodbc. La ENGINE valeur demeure "mssql" dans les deux cas.

Opter un alias dans mssql-python

Définissez l’option python_driver dans le dictionnaire de OPTIONS cet alias :

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<database>",
        "USER": "<user_id>",
        "PASSWORD": "<password>",
        "HOST": "<server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "python_driver": "mssql_python",
            "extra_params": "Encrypt=yes",
        },
    },
}

Le backend accepte "mssql_python", "mssql-python", et "python", et la comparaison ignore le cas. Omets-le python_driver, laisse-le vide, ou mets-le sur "pyodbc" pour garder le pilote par défaut. Comme le paramètre est par alias, vous revenez en arrière une base de données à la fois en supprimant cette option.

Le mssql-python module n’est importé que lorsqu’un alias le sélectionne. Si la version installée est antérieure à 1.15.0, le backend génère ImproperlyConfigured indiquant la version requise.

Configuration requise pour l’installation

pip install mssql-django Installe les deux pilotes. Le mssql-python chemin n’a pas d’installation de pilote ODBC séparé. Une installation avec --no-deps, ou un index privé qui n’est pas un miroir de mssql-python, fait que le paquet est absent et l’alias échoue lors de l’import.

Installez les prérequis de la plateforme pour mssql-python, y compris OpenSSL sur macOS et les bibliothèques requises sous Linux.

Comme mssql-python est une dépendance requise, mssql-django 2.0 ne s’installe que sur les plateformes disposant d’une distribution mssql-python compatible. Pour la liste des plateformes, voir le support et le cycle de vie de mssql-django.

Différences de comportement

Les deux pilotes construisent des chaînes de connexion différentes et exposent des mots-clés de connexion différents. Lisez cette section avant de changer d’alias.

Paramètres de connexion

Setting pyodbc mssql-python
HOST et PORT Émis comme SERVER, SERVERNAME, ou SERVER plus PORT, selon le pilote et host_is_server. Toujours émis comme SERVER=<host>,<port>. Un vide HOST devient localhost.
driver Sélectionne le pilote ODBC. Utilise par défaut le pilote ODBC Driver 18 de Microsoft pour SQL Server, avec basculement automatique vers le pilote 17. Ignoré. Il n’y a pas de solution de secours pour le Driver 17.
dsn Soutenu. Ignoré.
host_is_server Pris en charge par FreeTDS. Ignoré.
unicode_results Soutenu. Ignoré.
TOKEN Soutenu. Soutenu. Fournir TOKEN sans USER, PASSWORD ou un mot-clé Authentication. Votre application acquiert et renouvelle le jeton.
DATABASE_CONNECTION_POOLING S’applique. S’applique.

Les délais d’expiration, les réessais, le niveau d’isolement, l’interclassement et return_rows_bulk_insert se comportent de la même manière sur les deux chemins.

Paramètres de connexion supplémentaires

mssql-python 1.15 vérifie extra_params par rapport à une liste d’autorisation et rejette tout ce qui n’y figure pas. Les mots-clés pris en charge incluent Authentication, Encrypt, TrustServerCertificate, HostnameInCertificate, ServerCertificate, ServerSPN, MultiSubnetFailover, ApplicationIntent, ConnectRetryCount, ConnectRetryInterval, KeepAliveInterval, KeepAlive, IpAddressPreference et PacketSize.

Le pilote rejette MARS_Connection, APP, LongAsMax et ColumnEncryption, ainsi que des mots-clés propres à pyodbc tels que WSID, AnsiNPW, QuotedId, UseFMTONLY, Network Library, Description, Regional, Current Language, Connect Timeout, SERVERNAME, DSN et DRIVER. Supprimez ces mots-clés avant de changer d’alias, et utilisez l’option connection_timeout à la place de Connect Timeout.

Lorsque extra_params définit un mot-clé que le backend génère également, la valeur explicitement définie l’emporte.

Jeux de résultats actifs multiples

Sur le pyodbc chemin, le backend ajoute MARS_Connection=yes lorsque l’alias utilise un pilote Microsoft ODBC sous Windows. Une valeur explicite MARS_Connection dans extra_params est honorée à la place, et la correspondance ignore le cas.

Le mssql-python chemin n’active jamais MARS, et il rejette le MARS_Connection mot-clé, donc vous ne pouvez pas activer MARS pour cet alias.

En l’absence de MARS, QuerySet.iterator() lit l’intégralité du résultat en mémoire avant de renvoyer les lignes afin qu’une requête imbriquée puisse réutiliser la connexion, et chunk_size n’y change rien. Prenez en compte le coût mémoire pour les ensembles de requêtes volumineux.

Pour les points de terminaison qui rejettent MARS, tels que Microsoft Fabric Warehouse, voir Désactiver MARS.

Configuration d’encodage

Les deux pilotes acceptent setencoding et setdecoding, et chaque entrée va à la méthode de connexion du pilote sélectionné. Chaque setdecoding entrée nécessite une sqltype clé sur les deux chemins, et la même entrée fonctionne sur l’un ou l’autre des pilotes. Une différence : mssql-python accepte -99 pour SQL_WMETADATA, et pyodbc la rejette.

Choisissez entre les pilotes

Pour tout nouveau développement, utilisez mssql-python. Cela supprime l’étape d’installation du pilote ODBC dans les images de conteneur et les déploiements d’App Service.

Utilisez pyodbc lorsque votre déploiement dépend d’un DSN nommé, de FreeTDS, d’Always Encrypted via le mot-clé ColumnEncryption, d’une version du pilote ODBC que vous gérez vous-même ou de MARS. Pour ce que MARS exige sur chaque chemin, voir Ensembles de résultats actifs multiples.

Les projets existants peuvent rester actifs pyodbc. Il reste le standard par défaut et est entièrement pris en charge. Lorsque vous effectuez la migration, modifiez un alias à la fois et exécutez votre suite de tests sur celui-ci avant de passer aux autres.

Contenu connexe

  • Last updated on