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

Este artigo explica as OPTIONS definições de dicionário na sua configuração do Django DATABASES. Estas definições controlam como mssql-django se liga ao SQL Server através do driver ODBC.

Seleção de pilotos ODBC

A partir da versão mssql-django 1.7, o backend usa por predefinição o ODBC Driver 18 para SQL Server. Se o Driver ODBC 18 não estiver instalado, o backend volta automaticamente ao ODBC Driver 17.

Note

O Driver ODBC 18 ativa Encrypt=yes por defeito e valida o certificado do servidor. Ligações que funcionavam com o Driver 17 podem falhar com um erro de confiança SSL/TLS. Para resolver a falha:

Para o SQL Server local, instale um certificado de servidor de uma autoridade certificadora em que os seus clientes já confiem, ou importe o certificado do servidor existente para cada repositório de confiança do cliente. Para instruções, consulte Configure Mecanismo de Banco de Dados do SQL Server para encriptar ligações.
Se estabelecer ligação através de um endereço IP ou de um alias que não corresponda ao sujeito do certificado ou ao respetivo nome alternativo do sujeito (SAN), adicione HostNameInCertificate=<name-from-certificate> a extra_params.

Para desenvolvimento local com um certificado autoassinado, veja TrustServerCertificate em Parâmetros ODBC adicionais.

Pode especificar explicitamente o driver:

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, também pode especificar o caminho completo para a biblioteca de drivers:

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

Pode ligar-se usando um HOST nome ou um DSN (Data Source Name) nomeado.

Ligar ao HOST

A maioria das configurações usa a HOST definição 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",
        },
    },
}

Liga-te à DSN

Use um DSN nomeado configurado nas 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 para True. Isto indica ao backend para usar HOST e PORT diretamente, em vez de procurar o nome de um 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 mais informações sobre ligações sem DSN com o FreeTDS, consulte o guia do utilizador do FreeTDS.

Parâmetros ODBC extra

Use extra_params para passar parâmetros adicionais de cadeia de ligação ODBC. O valor é uma cadeia delimitada por ponto e vírgula adicionada à cadeia de ligaçã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",
        },
    },
}

Esta definição também é usada para palavras-chave de autenticação Microsoft Entra.

Caution

Uso TrustServerCertificate=yes apenas para desenvolvimento local com certificados auto-assinados. Não o uses na produção. Desativa a validação da cadeia de certificados e aumenta o risco de ataque de intermediário. Instale um certificado de confiança no servidor e ligue-se a TrustServerCertificate=no.

Tempos de espera e tentativas de ligação

Configure a resiliência da ligação com as definições de timeout e de novas tentativas:

Option	Predefinição	Description
`connection_timeout`	`0` (desativado)	Segundos máximos para esperar por uma ligação.
`connection_retries`	`5`	Número de tentativas de repetição por falha de ligação.
`connection_retry_backoff_time`	`5`	Número de segundos de espera entre tentativas de repetição.
`query_timeout`	`0` (desativado)	Segundos máximos para esperar que uma consulta seja concluída.

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 colação personalizada para consultas de campos 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",
        },
    },
}

Múltiplas ligações a bases de dados

O Django suporta a ligação a múltiplas bases de dados em simultâneo. Isto é útil para réplicas de leitura, consultas entre bases de dados ou para separar cargas de trabalho consoante o nível de isolamento.

Configurar múltiplas bases de dados

Defina cada ligação na definiçã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",
        },
    },
}

Caution

READ UNCOMMITTED permite leituras sujas. Use este nível de isolamento apenas para relatórios ou consultas de análise onde não é necessária precisão absoluta. Para mais informações, consulte Gestão de Transações.

Encaminhar consultas com um encaminhador de base de dados

Crie um router de base de dados para direcionar as operações de leitura e escrita para a ligaçã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"

Registe o router em settings.py:

DATABASE_ROUTERS = ["myproject.routers.ReadReplicaRouter"]

Guarde a classe router num ficheiro como myproject/routers.py.

Consultar diretamente uma base de dados específica

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

# 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 mais informações sobre níveis de isolamento em bases de dados por ligação, consulte Ler dados sem bloqueio.

Comentários

Esta página foi útil?

Last updated on 2026-07-01