Referência de configuração MSSQL-Django

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

Configuração mínima

O exemplo a seguir 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",
        },
    },
}

Configurações de conexão com banco de dados

Essas configurações configuram sua DATABASES conexão. A maioria são configurações padrão de Django; Exceções são observadas:

Setting	Tipo	Description
`ENGINE`	String	Deve ser `"mssql"`.
`NAME`	String	Nome do banco de dados. Obrigatório
`HOST`	String	Nome do host ou endereço IP do servidor. 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 do usuário do banco de dados. Se não for concedido, o Windows Integrated Security é utilizado.
`PASSWORD`	String	Senha do usuário do banco de dados.
`AUTOCOMMIT`	booleano	Configurado para `False` desativar o gerenciamento de transações do Django. O padrão é `True`.
`Trusted_Connection`	String	Defina para `"yes"` (padrão) 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"` desabilitar explicitamente a autenticação do Windows. Isso é 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`). Isso é uma `mssql-django` extensão, não uma configuração padrão do Django.

Configurações de TESTE

Essas configurações controlam o banco de dados de testes usado pelo executor de testes do Django:

Setting	Tipo	Description
`NAME`	String	Nome do banco de dados de teste. Padrão: `"test_" + NAME`.
`COLLATION`	String	Coletão para o banco de dados de testes. Padrão: padrão da instância.
`DEPENDENCIES`	List	Dependências da ordem de criação do banco de dados.
`MIRROR`	String	Alias de um banco 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 configurações específicas do backend. Coloque estas configurações dentro do DATABASES["default"]["OPTIONS"] dicionário:

Opção	Tipo	Default	Description
`driver`	String	`"ODBC Driver 18 for SQL Server"`	Driver ODBC para usar. Automaticamente volta para o Driver 17 se o 18 não estiver instalado.
`isolation_level`	String	`None`	Nível de isolamento da transação: `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 FreeTDS em vez de um `freetds.conf` nome de servidor de dados.
`unicode_results`	booleano	`False`	Ative a função do `unicode_results` pyodbc.
`extra_params`	String	`None`	Parâmetros adicionais ODBC no `"param=value;param=value"` formato. Usado para autenticação Microsoft Entra.
`collation`	String	`None`	Colação para consultas em campos de texto (por exemplo, `"Chinese_PRC_CI_AS"`).
`connection_timeout`	Integer	`0`	Tempo de conexão em segundos (`0` = desativado).
`connection_retries`	Integer	`5`	Número de tentativas de retentativa de conexão.
`connection_retry_backoff_time`	Integer	`5`	Tempo de recuo em segundos entre as tentativas.
`query_timeout`	Integer	`0`	Consulta em segundos (`0` = desativado).
`setencoding` / `setdecoding`	List	`None`	Configuração de decodificação / codificada PYODBC.
`return_rows_bulk_insert`	booleano	`False`	Permita que as fileiras retornem a partir da inserção em massa. Deve ser `False` se as mesas têm gatilhos.
`datefirst`	Integer	`7`	Primeiro dia da semana para `SET DATEFIRST`. `7`é domingo (padrão do 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. Essa 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 padrão 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 detecta automaticamente a codificação.
`connection_recovery_interval_msec`	Float	`0.0`	Milissegundos para esperar entre tentativas de retentativa no loop de recuperação de conexão do backend após um erro de rede. Aumente esse valor para links 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,
        },
    },
}

Configurações específicas do backend

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

Setting	Tipo	Default	Description
`DATABASE_CONNECTION_POOLING`	booleano	`True`	Configura para `False` desabilitar o pool de conexão 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