Opções de conexão para mssql-django

Este artigo explica as configurações do dicionário OPTIONS na sua configuração do Django DATABASES. Essas configurações controlam como mssql-django se conecta ao SQL Server.

Seleção de drivers de banco de dados em Python

mssql-djangoAs versões 2.0 e posteriores se conectam por meio de pyodbc, que é o padrão, ou do driver mssql-python da Microsoft. Selecione mssql-python para um alias de banco de dados com a opção python_driver:

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

Não defina driver nesse caminho. O caminho mssql-python ignora as opções driver, dsn, host_is_server e unicode_results, valida extra_params em relação a uma lista de permissões e não habilita MARS. Para a lista completa de diferenças de comportamento, veja Selecionar o driver de banco de dados para mssql-django. O restante deste artigo descreve o caminho padrão pyodbc, salvo indicação em contrário.

Seleção do driver ODBC

No caminho pyodbc, o backend usa por padrão o ODBC Driver 18 for SQL Server. Se o ODBC Driver 18 não estiver instalado, o back-end retornará automaticamente ao ODBC Driver 17. Um driver configurado explicitamente não recorre a uma alternativa.

Note

O ODBC Driver 18 habilita Encrypt=yes por padrão e valida o certificado do servidor. As conexões que funcionaram com o Driver 17 podem falhar com um erro de confiança SSL/TLS. Para resolver a falha:

Para SQL Server locais, instale um certificado de servidor de uma autoridade de certificação em que os clientes já confiam ou importe o certificado de servidor existente para cada repositório de confiança do cliente. Para obter instruções, consulte Configurar Mecanismo de Banco de Dados do SQL Server para criptografar conexões.
Se você se conectar por endereço IP ou a um alias que não corresponde ao assunto do certificado ou ao nome alternativo do assunto (SAN), adicione HostNameInCertificate=<name-from-certificate> a extra_params.

Para desenvolvimento local com um certificado autoassinado, consulte TrustServerCertificate em Parâmetros ODBC extras.

Você pode especificar o driver explicitamente:

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

No Linux, você também pode especificar o caminho completo para a biblioteca de driver:

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 vs HOST

Você pode se conectar usando um nome HOST ou um DSN nomeado (Nome da Fonte de Dados).

Conectar-se ao HOST

A maioria das configurações usa a configuração HOST diretamente:

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

Conectar-se ao DSN

Use um DSN nomeado configurado em suas fontes de dados ODBC:

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

Suporte ao FreeTDS

Para usar o FreeTDS como driver ODBC, defina host_is_server como True. Isso instrui o backend a usar HOST e PORT diretamente, em vez de procurar um nome de servidor de dados em 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,
        },
    },
}

Para obter mais informações sobre conexões sem DSN com o FreeTDS, consulte o guia do usuário do FreeTDS.

Parâmetros ODBC extras

Use extra_params para passar parâmetros de cadeia de conexão ODBC adicionais. O valor é uma cadeia de caracteres delimitada por ponto-e-vírgula acrescentada ao cadeia de conexão:

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

Essa configuração também é usada para palavras-chave de autenticação do Microsoft Entra.

Ao conectar-se ao Banco de Dados SQL do Azure, à Instância Gerenciada de SQL do Azure, ao banco de dados SQL no Microsoft Fabric, a um ouvinte de grupo de disponibilidade ou a uma instância de cluster de failover, adicione MultiSubnetFailover=Yes a extra_params. Quando o nome do servidor se resolve para mais de um endereço IP, o driver se conecta a todos esses endereços ao mesmo tempo e usa o primeiro que responde. Sem ele, o driver tenta os endereços um de cada vez, e um endereço que não responde consome o tempo limite restante da autenticação antes de passar para o próximo. Quando o DNS é resolvido para um único endereço, o driver faz uma única tentativa de conexão, portanto, é seguro deixar a configuração ativada.

MultiSubnetFailover=Yes possui os seguintes limites:

Você não pode usá-lo em um protocolo que não seja o TCP.
A conexão a uma instância do SQL Server configurada com mais de 64 endereços IP falha.
Você não pode usá-lo com espelhamento de banco de dados. O driver retorna um erro quando a cadeia de conexão especifica Failover_Partner e também quando o servidor informa que o banco de dados está espelhado. O espelhamento de banco de dados está obsoleto em todas as versões suportadas do SQL Server. Use Grupos de disponibilidade AlwaysOn em vez disso.

Cuidado

Use TrustServerCertificate=yes somente para desenvolvimento local com certificados autoassinados. Não o use em produção. Desabilita a validação da cadeia de certificados e aumenta o risco de ataque de intermediário. Instale um certificado confiável no servidor e conecte-se com TrustServerCertificate=no.

Desativar MARS

No caminho pyodbc, o backend habilita Multiple Active Result Sets (MARS) por padrão quando usa um driver ODBC da Microsoft no Windows. Alguns endpoints rejeitam a MARS_Connection palavra-chave, incluindo o Microsoft Fabric Warehouse. Para se conectar a um desses endpoints, configure MARS_Connection=no no extra_params desse 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",
        },
    },
}

A partir da mssql-django 2.0, um valor explícito MARS_Connection é respeitado, e a correspondência ignora o caso, para que o backend não adicione um padrão conflitante. Na versão 1.8.0 e versões anteriores, o padrão do Windows sobrescrevia o valor explícito e a conexão falhava.

Com o MARS desativado, QuerySet.iterator() lê o resultado completo na memória antes de gerar linhas, para que uma consulta aninhada possa reutilizar a conexão. Considere o custo de memória em grandes conjuntos de consultas.

Para outros métodos de autenticação, mantenha as configurações correspondentes e adicione MARS_Connection=no a extra_params. Essa configuração de conexão não implica suporte total ao Microsoft Fabric Warehouse para migrações do Django ou outros recursos do SQL Server.

O mssql-python caminho não ativa o MARS e rejeita a MARS_Connection palavra-chave, então essa configuração se aplica apenas a pyodbc.

Tempo limite de conexão e novas tentativas

Configure a resiliência da conexão com configurações de tempo limite e nova tentativa:

Opção	Default	Descrição
`connection_timeout`	`0` (desabilitado)	Número máximo de segundos para esperar por uma conexão.
`connection_retries`	`5`	Número de tentativas em caso de falha na conexão.
`connection_retry_backoff_time`	`5`	Número de segundos de espera entre as tentativas.
`query_timeout`	`0` (desabilitado)	Máximo de segundos para aguardar a conclusão de uma consulta.

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",
            "connection_timeout": 30,
            "connection_retries": 3,
            "connection_retry_backoff_time": 10,
            "query_timeout": 120,
        },
    },
}

connection_timeout=0 é o padrão do mssql-django. Como o pyodbc só chama SQLSetConnectAttr(SQL_ATTR_LOGIN_TIMEOUT, ...) quando você fornece um valor positivo, o padrão dependente do driver se aplica (15 segundos para o Microsoft ODBC Driver for SQL Server). Defina um valor explícito para que tentativas de conexão não responsivas falhem previsivelmente.

Se o destino for o Banco de Dados SQL do Azure sem servidor com a pausa automática habilitada, use pelo menos 60. Um banco de dados pausado automaticamente retoma na primeira tentativa de conexão, e essa tentativa pode falhar com o erro 40613 enquanto o banco de dados recomeça. Com um tempo limite mais curto, a primeira tentativa de conexão expira antes que a retomada seja concluída. connection_retries por fim consegue, mas a primeira solicitação passa por vários timeouts antes de se conectar. Para mais informações, consulte Pausa automática e retomada automática.

Collation

Defina uma ordenação personalizada para pesquisas de campo de texto:

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

Várias conexões de banco de dados

O Django dá suporte à conexão a vários bancos de dados simultaneamente. Isso é útil para réplicas de leitura, consultas entre bancos de dados ou para separar cargas de trabalho por nível de isolamento.

Configurar vários bancos de dados

Defina cada conexão na configuração DATABASES:

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

Cuidado

READ UNCOMMITTED permite leituras sujas. Use esse nível de isolamento apenas para consultas de relatório ou análise em que a precisão absoluta não é necessária. Para obter mais informações, consulte Gerenciamento de transações.

Rotear consultas com um roteador de banco de dados

Crie um roteador de banco de dados para direcionar operações de leitura e gravação para a conexão apropriada:

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"

Registre o roteador em settings.py:

DATABASE_ROUTERS = ["myproject.routers.ReadReplicaRouter"]

Salve a classe de roteador em um arquivo como myproject/routers.py.

Consultar um banco de dados específico diretamente

Use o using() método para consultar um alias de banco de dados específico:

# 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)

Para obter mais informações sobre os níveis de isolamento em bancos de dados por conexão, consulte Ler dados sem bloquear.

Comentários

Esta página foi útil?

Last updated on 2026-09-29