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 a SQL Server por meio do driver ODBC.

Seleção do driver ODBC

A partir da mssql-django versão 1.7, o back-end usa como padrão o Driver ODBC 18 para SQL Server. Se o ODBC Driver 18 não estiver instalado, o back-end retornará automaticamente ao ODBC Driver 17.

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 ao Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure, SQL Database no Microsoft Fabric, um ouvinte de grupo de disponibilidade ou uma instância de cluster de failover, adicionam MultiSubnetFailover=Yes a extra_params. O driver tenta conexões com todos os endpoints resolvidos em paralelo e completa a autenticação com o primeiro responsivo. É seguro em alvos de IP único: quando o DNS resolve para um único endereço, o driver faz uma única tentativa de conexão sem overhead mensurável, então você pode deixar a configuração ativada para todas as implantações do Django que miram um endpoint da família Microsoft SQL.

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.

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 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 alvo for Banco de Dados SQL do Azure serverless com autopausa ativada, use pelo menos 60. Um banco de dados pausado automaticamente é retomado na primeira conexão, e a retomada pode levar de 30 a 60 segundos ou mais. Com um tempo de espera menor, a primeira tentativa de conexão expira antes da retomada terminar. connection_retries se recupera eventualmente, mas a primeira solicitação paga vários intervalos de tempo antes de ter sucesso.

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-08-13