Riferimento configurazione MSSQL-Django

Questo articolo è il riferimento completo settings.py alla configurazione per il mssql-django backend del database Django. Configura la connettività di SQL Server modificando il DATABASES dizionario nel file del settings.py tuo progetto Django.

Configurazione minima

Il seguente esempio mostra la configurazione minima richiesta per il percorso predefinito pyodbc :

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",
        },
    },
}

Per eseguire l'alias mssql-python invece, imposta python_driver e ometti driver. Il mssql-python percorso ignora driver:

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

ENGINE rimane "mssql" su entrambe le strade. Gli alias nello stesso progetto possono usare driver diversi. Per l'elenco completo delle differenze di comportamento, vedi Seleziona il driver del database per mssql-django.

Salvo indicazione, gli esempi nel resto di questo articolo mostrano il percorso predefinito pyodbc .

Impostazioni di connessione al database

Queste impostazioni configurano la tua DATABASES connessione. La maggior parte sono impostazioni standard di Django; Si annotano eccezioni:

Setting	Tipo	Descrizione
`ENGINE`	String	Deve essere `"mssql"`.
`NAME`	String	nome del database. Obbligatorio.
`HOST`	String	Nome host server o indirizzo IP. Usa `"server\\instance"` il formato per le istanze nominate.
`PORT`	String	Porta di istanza server. Stringa vuota significa porta predefinita.
`USER`	String	Nome dell'utente del database. Se non viene fornita, viene utilizzata la sicurezza integrata di Windows.
`PASSWORD`	String	Password utente del database.
`AUTOCOMMIT`	Booleano	Imposta su `False` per disabilitare la gestione delle transazioni di Django. Il valore predefinito è `True`.
`Trusted_Connection`	String	Impostato su `"yes"` (di default) per usare la sicurezza integrata di Windows quando `USER` non è fornito. Quando `USER` e `PASSWORD` sono entrambi impostati, queste credenziali hanno la precedenza e `Trusted_Connection` vengono ignorate. Imposta su `"no"` per disabilitare autenticazione di Windows esplicitamente. Questa è un'estensione `mssql-django` , non un'impostazione standard di Django.
`TOKEN`	String	Token di accesso per l'autenticazione Microsoft Entra (ad esempio, tramite `azure.identity`). Questa è un'estensione `mssql-django` , non un'impostazione standard di Django.

Impostazioni TEST

Queste impostazioni controllano il database di test utilizzato dal testrunner di Django:

Setting	Tipo	Descrizione
`NAME`	String	Nome del database del test. Impostazione predefinita: `"test_" + NAME`.
`COLLATION`	String	Collazione per il database di test. Predefinito: istanza predefinito.
`DEPENDENCIES`	List	Dipendenze dell'ordine di creazione del database.
`MIRROR`	String	Alias di un database da speculare durante i test.

Example:

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",
        },
        "TEST": {
            "NAME": "test_mydb",
            "COLLATION": "SQL_Latin1_General_CP1_CI_AS",
        },
    },
}

OPZIONI

Il OPTIONS dizionario fornisce configurazioni specifiche per il backend. Inserisci queste impostazioni all'interno del DATABASES["default"]["OPTIONS"] dizionario:

Opzione	Tipo	Valore predefinito	Descrizione
`python_driver`	String	Non impostato	Imposta per `"mssql_python"` collegare questo alias tramite il `mssql-python` driver. Non imposta o `"pyodbc"` mantiene il driver predefinito `pyodbc` . Vedi Seleziona il driver del database per mssql-django.
`driver`	String	`"ODBC Driver 18 for SQL Server"`	Driver ODBC da usare. Torna automaticamente al Driver 17 se il 18 non è installato. Ignorato sul `mssql-python` sentiero.
`isolation_level`	String	`None`	Livello di isolamento delle transazioni: `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READSNAPSHOT`, o `SERIALIZABLE`.
`dsn`	String	`None`	Si chiama DSN. Può essere usato al posto di `HOST`. Ignorato sul `mssql-python` sentiero.
`host_is_server`	Booleano	`False`	Impostato per `True` usare `HOST`/`PORT` direttamente con FreeTDS invece che con il nome di `freetds.conf` un dataserver. Ignorato sul `mssql-python` sentiero.
`unicode_results`	Booleano	`False`	Attiva la funzione di `unicode_results` pyodbc. Ignorato sul `mssql-python` sentiero.
`extra_params`	String	`None`	Parametri aggiuntivi di stringa di connessione nel `"param=value;param=value"` formato. Utilizzato per l'autenticazione Microsoft Entra. Il `mssql-python` percorso li valida rispetto a una lista di permessi.
`collation`	String	`None`	Colazione per le ricerche nei campi di testo (ad esempio, `"Chinese_PRC_CI_AS"`).
`connection_timeout`	Numero intero	`0`	Timeout della connessione in secondi (`0` = disabilitato). Usa almeno 60 per database SQL di Azure serverless con auto-pausa attivata. Un database in pausa automatica riprende al primo tentativo di connessione, e questo tentativo può fallire con l'errore 40613 mentre il database riprende, quindi l'applicazione deve riprovare. Per ulteriori informazioni, vedi Pausa automatica e ripresa automatica.
`connection_retries`	Numero intero	`5`	Numero di tentativi di ritentazione di connessione.
`connection_retry_backoff_time`	Numero intero	`5`	Tempo di retrocesso in secondi tra un tentativo e l'altro.
`query_timeout`	Numero intero	`0`	Timeout della query in secondi (`0` = disabilitato).
`setencoding` / `setdecoding`	List	`None`	La configurazione di codifica e decodifica passava ai metodi di connessione del driver selezionato. Ogni `setdecoding` voce richiede una `sqltype` chiave su entrambi i percorsi, e la stessa voce funziona su entrambi i driver. `mssql-python` accetta `-99` per `SQL_WMETADATA`, e `pyodbc` lo rifiuta. Vedi il riferimento per la codifica e la decodifica pyodbc.
`return_rows_bulk_insert`	Booleano	`False`	Consentire il ritorno delle file da inserimento in massa. Deve essere così `False` se le tabelle hanno trigger.
`datefirst`	Numero intero	`7`	Primo giorno della settimana per `SET DATEFIRST`. `7`è domenica (predefinito SQL Server), `1` è lunedì.
`driver_needs_utf8`	Opzione solo presenza	Non impostato	Abilita la codifica UTF-8 per il driver ODBC. Questa opzione è abilitata quando la chiave è presente in `OPTIONS`; il valore stesso viene ignorato. Tipicamente necessario con FreeTDS o configurazioni unixODBC più vecchie che predefinivano su Latin-1.
`driver_charset`	String	`None`	Set di caratteri esplicito per il driver ODBC (ad esempio, `"UTF-8"`). Usa con `driver_needs_utf8` quando il driver non rileva automaticamente la codifica.
`connection_recovery_interval_msec`	Float	`0.0`	Millisecondi di attesa tra un tentativo di ripresa e l'altro nel ciclo di recupero della connessione del backend dopo un errore di rete. Aumenta questo valore per collegamenti di rete instabili.

Esempio con opzioni comuni:

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": "Encrypt=yes",
            "isolation_level": "READ COMMITTED",
            "connection_timeout": 30,
            "connection_retries": 3,
            "connection_retry_backoff_time": 5,
            "query_timeout": 60,
        },
    },
}

Impostazioni specifiche del backend

Questa impostazione è posta a livello di modulo in settings.py, fuori dal DATABASES dizionario:

Setting	Tipo	Valore predefinito	Descrizione
`DATABASE_CONNECTION_POOLING`	Booleano	`True`	Imposta per `False` disabilitare il pooling di connessione a livello di driver. Si applica sia `pyodbc` a che `mssql-python`a .

Example:

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",
        },
    },
}

# Set this to False to disable driver-level connection pooling
DATABASE_CONNECTION_POOLING = False

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-09-29