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.

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 se conectar ao Banco de Dados SQL do Azure, ao Instância Gerenciada de SQL do Azure, a um 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 resolve para um único endereço, o driver faz uma única tentativa de conexão, então a configuração é segura para deixar 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 indica 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.

Tempo limite de conexão e novas tentativas

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

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 alvo for Banco de Dados SQL do Azure serverless com autopausa ativada, 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 de espera menor, a primeira tentativa de conexão expira antes da retomada terminar. 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",
        },
    },
}

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.

Conteúdo relacionado

• Referência de configuração mssql-django
• Autenticação do Microsoft Entra com mssql-django
• Lógica de repetição e resiliência da conexão com mssql-django
• Práticas recomendadas de segurança para mssql-django
• Pool de conexões no mssql-django
• Solucionar problemas de mssql-django