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.

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

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-07-01