Options de connexion pour mssql-django

Cet article explique les paramètres du OPTIONS dictionnaire dans votre configuration Django DATABASES . Ces réglages contrôlent la façon dont mssql-django il se connecte à SQL Server.

Sélection des pilotes de base de données Python

mssql-django Les versions 2.0 et ultérieures se connectent soit via pyodbc, le pilote par défaut, soit via le pilote mssql-python de Microsoft. Sélectionnez mssql-python pour un alias de base de données avec l’option python_driver :

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

Ne définissez pas driver sur ce chemin. Le chemin mssql-python ignore les options driver, dsn, host_is_server et unicode_results, valide extra_params par rapport à une liste d’autorisation et n’active pas MARS. Pour la liste complète des différences de comportement, voir Sélectionner le pilote de base de données pour mssql-django. Le reste de cet article décrit le chemin par défaut pyodbc , sauf indication contraire.

Sélection du pilote ODBC

Sur le pyodbc chemin, le backend utilise par défaut le pilote ODBC 18 pour SQL Server. Si ODBC Driver 18 n’est pas installé, le back-end revient automatiquement au pilote ODBC 17. Un pilote explicitement configuré ne revient pas à une solution de repli.

Note

ODBC Driver 18 active Encrypt=yes par défaut et valide le certificat de serveur. Les connexions qui ont fonctionné avec driver 17 peuvent échouer avec une erreur d’approbation SSL/TLS. Pour résoudre l’échec :

Pour les SQL Server locales, installez un certificat de serveur à partir d’une autorité de certification que vos clients approuvent déjà, ou importez le certificat de serveur existant dans chaque magasin d’approbations client. Pour obtenir des instructions, consultez Configurer Moteur de base de données SQL Server pour chiffrer les connexions.
Si vous vous connectez par adresse IP ou par un alias qui ne correspond pas à l’objet ou au nom d’autre objet du certificat (SAN), ajoutez-y HostNameInCertificate=<name-from-certificate>extra_params.

Pour le développement local avec un certificat auto-signé, consultez TrustServerCertificate dans Paramètres ODBC supplémentaires.

Vous pouvez spécifier explicitement le pilote :

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 17 for SQL Server",
        },
    },
}

Sur Linux, vous pouvez également spécifier le chemin complet de la bibliothèque de pilotes :

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "/opt/microsoft/msodbcsql18/lib64/libmsodbcsql-18.0.so.1.1",
        },
    },
}

DSN et HOST

Vous pouvez vous connecter à l’aide d’un HOST nom ou d’un DSN nommé (nom de la source de données).

Se connecter avec HOST

La plupart des configurations utilisent directement le HOST paramètre :

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

Se connecter avec DSN

Utilisez un DSN nommé configuré dans vos sources de données ODBC :

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "OPTIONS": {
            "dsn": "MyDataSourceName",
        },
    },
}

Prise en charge de FreeTDS

Pour utiliser FreeTDS comme pilote ODBC, définissez host_is_server sur True. Cela indique au back-end d’utiliser HOST et PORT directement au lieu de rechercher un nom de serveur de données dans freetds.conf:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "FreeTDS",
            "host_is_server": True,
        },
    },
}

Pour plus d’informations sur les connexions sans DSN avec FreeTDS, consultez le guide de l’utilisateur FreeTDS.

Paramètres ODBC supplémentaires

Utilisez extra_params pour transmettre des paramètres supplémentaires de la chaîne de connexion ODBC. La valeur est une chaîne délimitée par des points-virgules ajoutée au chaîne de connexion :

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "TrustServerCertificate=yes;ApplicationIntent=ReadOnly",
        },
    },
}

Ce paramètre est également utilisé pour les mots-clés d’authentification Microsoft Entra.

Lors de la connexion à Azure SQL Database, Azure SQL Managed Instance, une base de données SQL dans Microsoft Fabric, un écouteur de groupe de disponibilité ou une instance de cluster de basculement, ajoutez MultiSubnetFailover=Yes à extra_params. Lorsque le nom du serveur se résout vers plus d’une adresse IP, le pilote se connecte à toutes ces adresses en même temps et utilise la première qui répond. Sans cela, le pilote essaie les adresses une par une, et une adresse qui ne répond pas consomme le délai d’authentification restant avant que le pilote ne passe à la suivante. Lorsque le DNS se résout à une seule adresse, le pilote effectue une seule tentative de connexion, donc le réglage est sûr à laisser activé.

MultiSubnetFailover=Yes a les limites suivantes :

Vous ne pouvez pas l’utiliser sur un autre protocole que TCP.
La connexion à une instance SQL Server configurée avec plus de 64 adresses IP échoue.
Vous ne pouvez pas l’utiliser avec la mise en miroir de bases de données. Le pilote renvoie une erreur lorsque la chaîne de connexion spécifie Failover_Partner, et aussi lorsque le serveur signale que la base de données est en miroir. Le miroir de base de données est obsolète dans toutes les versions supportées de SQL Server. Utilisez plutôt les groupes de disponibilité Always On.

Caution

Utilisez TrustServerCertificate=yes uniquement pour le développement local avec des certificats auto-signés. Ne l’utilisez pas en production. Cela désactive la validation de la chaîne de certificats et augmente le risque d'attaque de type adversaire du milieu. Installez un certificat approuvé sur le serveur et connectez-vous avec TrustServerCertificate=no.

Désactiver MARS

Sur le pyodbc chemin, le backend active par défaut les ensembles de résultats actifs multiples (MARS) lorsqu’il utilise un pilote Microsoft ODBC sous Windows. Certains points de terminaison rejettent le MARS_Connection mot-clé, notamment Microsoft Fabric Warehouse. Pour vous connecter à l’un de ces points de terminaison, définissez MARS_Connection=no dans le extra_params de cet alias :

DATABASES = {
    "warehouse": {
        "ENGINE": "mssql",
        "NAME": "<database>",
        "USER": "<user_id>",
        "PASSWORD": "<password>",
        "HOST": "<server>.datawarehouse.fabric.microsoft.com",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryServicePrincipal;MARS_Connection=no",
        },
    },
}

À partir de la version mssql-django 2.0, une valeur MARS_Connection explicite est prise en compte, et la correspondance ne tient pas compte de la casse, de sorte que le backend n’ajoute pas de valeur par défaut conflictuelle. Dans la version 1.8.0 et les versions antérieures, le défaut de Windows écrasait la valeur explicite et la connexion échouait.

Avec MARS désactivé, QuerySet.iterator() il lit le résultat complet en mémoire avant de fournir des lignes afin qu’une requête imbriquée puisse réutiliser la connexion. Prenez en compte le coût mémoire pour les ensembles de requêtes volumineux.

Pour d’autres méthodes d’authentification, conservez les paramètres d’authentification correspondants et ajoutez MARS_Connection=no à extra_params. Ce réglage de connexion n'implique pas la prise en charge complète de Microsoft Fabric Warehouse pour les migrations de Django ou d'autres fonctionnalités de SQL Server.

Le mssql-python chemin n’active pas MARS et rejette le MARS_Connection mot-clé, donc ce paramètre ne s’applique qu’à pyodbc.

Délais d'expiration des connexions et nouvelles tentatives

Configurez la résilience des connexions avec les paramètres de délai d’attente et de nouvelle tentative :

Option	Par défaut	Description
`connection_timeout`	`0` (désactivé)	Nombre maximal de secondes à attendre pour une connexion.
`connection_retries`	`5`	Nombre de tentatives de nouvelle tentative en cas d’échec de connexion.
`connection_retry_backoff_time`	`5`	Nombre de secondes d'attente entre les nouvelles tentatives.
`query_timeout`	`0` (désactivé)	Nombre maximal de secondes pour attendre la fin d’une requête.

Exemple :

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "connection_timeout": 30,
            "connection_retries": 3,
            "connection_retry_backoff_time": 10,
            "query_timeout": 120,
        },
    },
}

connection_timeout=0 est la valeur par défaut de mssql-django. Comme pyodbc n’appelle SQLSetConnectAttr(SQL_ATTR_LOGIN_TIMEOUT, ...) que lorsque vous fournissez une valeur positive, le défaut dépendant du pilote s’applique (15 secondes pour le pilote ODBC Microsoft pour SQL Server). Définissez une valeur explicite pour que les tentatives de connexion non réactives échouent de manière prévisible.

Si la cible est Azure SQL Database sans serveur avec l’auto-pause activée, utilisez au moins 60. Une base de données en pause automatique reprend lors de la première tentative de connexion, et cette tentative peut échouer avec l’erreur 40613 pendant que la base de données reprend. Avec un délai d’expiration plus court, la première tentative de connexion expire avant que la reprise ne soit terminée. connection_retries Finalement, elle réussit, mais la première demande attend plusieurs temps d’attente avant de se connecter. Pour plus d’informations, voir Mise en pause automatique et reprise automatique.

Collation

Définissez un classement personnalisé pour les recherches de champs de texte :

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "collation": "Chinese_PRC_CI_AS",
        },
    },
}

Connexions à plusieurs bases de données

Django prend en charge la connexion à plusieurs bases de données simultanément. Cela est utile pour les réplicas en lecture, les requêtes entre bases de données ou la séparation des charges de travail selon le niveau d'isolation.

Configurer plusieurs bases de données

Définissez chaque connexion dans le DATABASES paramètre :

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "app_db",
        "HOST": "<your-primary-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
    "readonly": {
        "ENGINE": "mssql",
        "NAME": "app_db",
        "HOST": "<your-readonly-replica>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Encrypt=yes;ApplicationIntent=ReadOnly",
        },
    },
    "analytics": {
        "ENGINE": "mssql",
        "NAME": "analytics_db",
        "HOST": "<your-analytics-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "isolation_level": "READ UNCOMMITTED",
        },
    },
}

Caution

READ UNCOMMITTED autorise les lectures incohérentes. Utilisez ce niveau d’isolation uniquement pour les requêtes de création de rapports ou d’analyse où la précision absolue n’est pas requise. Pour plus d’informations, consultez Gestion des transactions.

Acheminer des requêtes avec un routeur de base de données

Créez un routeur de base de données pour diriger les opérations de lecture et d’écriture dans la connexion appropriée :

class ReadReplicaRouter:
    """Route read queries to the readonly replica, writes to the primary."""

    def db_for_read(self, model, **hints):
        return "readonly"

    def db_for_write(self, model, **hints):
        return "default"

    def allow_relation(self, obj1, obj2, **hints):
        return True

    def allow_migrate(self, db, app_label, model_name=None, **hints):
        return db == "default"

Inscrivez le routeur dans settings.py:

DATABASE_ROUTERS = ["myproject.routers.ReadReplicaRouter"]

Enregistrez la classe de routeur dans un fichier tel que myproject/routers.py.

Interroger une base de données spécifique directement

Utilisez la using() méthode pour interroger un alias de base de données spécifique :

# Explicit read from analytics database
reports = AnalyticsReport.objects.using("analytics").filter(date__gte="2025-01-01")

# Write to default
Product.objects.create(name="Widget", price=9.99)

Pour plus d’informations sur les niveaux d’isolation sur les bases de données par connexion, consultez Lire les données sans bloquer.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-09-29