Referência de configuração MSSQL-Django

Este artigo é a referência completa settings.py de configuração para o mssql-django backend da base de dados Django. Configure a conectividade do SQL Server editando o DATABASES dicionário no ficheiro do settings.py seu projeto Django.

Configuração mínima

O exemplo seguinte mostra a configuração mínima necessária:

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

Definições de ligação à base de dados

Estas definições configuram a sua DATABASES ligação. A maioria são configurações padrão de Django; São anotadas exceções:

Setting	Tipo	Description
`ENGINE`	String	Deve ser `"mssql"`.
`NAME`	String	Nome do banco de dados. Required.
`HOST`	String	Nome do host do servidor ou endereço IP. Use `"server\\instance"` o formato para instâncias nomeadas.
`PORT`	String	Porta de instância de servidor. String vazia significa porta padrão.
`USER`	String	Nome de usuário do banco de dados. Se não for concedido, é utilizado o Windows Integrated Security.
`PASSWORD`	String	Palavra-passe do utilizador da base de dados.
`AUTOCOMMIT`	booleano	Definido para `False` desativar a gestão de transações do Django. A predefinição é `True`.
`Trusted_Connection`	String	Definido para `"yes"` (por defeito) para usar o Windows Integrated Security quando `USER` não for fornecido. Quando `USER` e `PASSWORD` ambos são definidos, essas credenciais têm prioridade e `Trusted_Connection` são ignoradas. Defina para `"no"` desativar explicitamente a Windows authentication. Isto é uma `mssql-django` extensão, não uma configuração padrão do Django.
`TOKEN`	String	Token de acesso para autenticação Microsoft Entra (por exemplo, via `azure.identity`). Isto é uma `mssql-django` extensão, não uma configuração padrão do Django.

Definições TEST

Estas definições controlam a base de dados de testes usada pelo executor de testes do Django:

Setting	Tipo	Description
`NAME`	String	Nome da base de dados de teste. Padrão: `"test_" + NAME`.
`COLLATION`	String	Compilação para a base de dados de testes. Padrão: instância por defeito.
`DEPENDENCIES`	Lista	Dependências da ordem de criação da base de dados.
`MIRROR`	String	Alias de uma base de dados para espelhar durante os testes.

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

OPÇÕES

O OPTIONS dicionário fornece uma configuração específica para o backend. Coloque estas definições dentro do DATABASES["default"]["OPTIONS"] dicionário:

Option	Tipo	Predefinição	Description
`driver`	String	`"ODBC Driver 18 for SQL Server"`	Driver ODBC para usar. Automaticamente volta ao Driver 17 se o 18 não estiver instalado.
`isolation_level`	String	`None`	Nível de isolamento de transações: `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, `SNAPSHOT`, ou `SERIALIZABLE`.
`dsn`	String	`None`	Chamado DSN. Pode ser usado em vez de `HOST`.
`host_is_server`	booleano	`False`	Defina para `True` usar`PORTHOST`/diretamente com o FreeTDS em vez de um `freetds.conf` nome de servidor de dados.
`unicode_results`	booleano	`False`	Ativa a funcionalidade do `unicode_results` pyodbc.
`extra_params`	String	`None`	Parâmetros ODBC adicionais no `"param=value;param=value"` formato. Usado para autenticação Microsoft Entra.
`collation`	String	`None`	Colação para consultas de campos de texto (por exemplo, `"Chinese_PRC_CI_AS"`).
`connection_timeout`	Integer	`0`	Tempo limite da ligação em segundos (`0` = desativado).
`connection_retries`	Integer	`5`	Número de tentativas de retentativa de ligação.
`connection_retry_backoff_time`	Integer	`5`	Tempo de recuo em segundos entre tentativas.
`query_timeout`	Integer	`0`	Consulta de tempo limite em segundos (`0` = desativado).
`setencoding` / `setdecoding`	Lista	`None`	Configuração de decodificação / de codificação pyodbc.
`return_rows_bulk_insert`	booleano	`False`	Permitir que as filas retornem a partir da inserção em massa. Deve ser `False` se as tabelas tiverem gatilhos.
`datefirst`	Integer	`7`	Primeiro dia da semana para `SET DATEFIRST`. `7`é domingo (padrão SQL Server), `1` é segunda-feira.
`driver_needs_utf8`	Opção apenas de presença	Não definido	Ative a codificação UTF-8 para o driver ODBC. Esta opção é ativada quando a chave está presente em `OPTIONS`; o valor em si é ignorado. Normalmente é necessário com FreeTDS ou configurações antigas de unixODBC que por defeito são Latin-1.
`driver_charset`	String	`None`	Conjunto de caracteres explícito para o driver ODBC (por exemplo, `"UTF-8"`). Use quando `driver_needs_utf8` o driver não detetar automaticamente a codificação.
`connection_recovery_interval_msec`	Flutuar	`0.0`	Milissegundos para esperar entre tentativas de retentativa no ciclo de recuperação de ligação do backend após um erro de rede. Aumente este valor para ligações de rede instáveis.

Exemplo com opções comuns:

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

Definições específicas do backend

Esta configuração é colocada ao nível do módulo em settings.py, fora do DATABASES dicionário:

Setting	Tipo	Predefinição	Description
`DATABASE_CONNECTION_POOLING`	booleano	`True`	Defina para `False` desativar o pool de ligações do pyodbc.

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 pyodbc's connection pooling
DATABASE_CONNECTION_POOLING = False

Comentários

Esta página foi útil?

Last updated on 2026-07-01