Strings de conexão para mssql-python

O driver mssql-python suporta as seguintes palavras-chave de cadeia de conexão ao conectar ao SQL Server, Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure e banco de dados SQL no Microsoft Fabric.

Sintaxe da cadeia de conexão

As strings de conexão usam pares chave-valor separados por ponto e vírgula:

keyword1=value1;keyword2=value2;...

Valores de enrolamento que contêm caracteres especiais (ponto e vírgula, sinais iguais ou colchetes curvados) em colchetes curvados:

PWD={my;complex=password}

Para incluir uma coltese de fechamento literal em um valor, use duas chaves de fechamento (}}):

PWD={password}}with}}brace}

Exemplos básicos de conexão

Os exemplos a seguir mostram como se conectar usando diferentes métodos de autenticação. Para aplicações de produção, utilize a autenticação Microsoft Entra sempre que possível. Ele elimina senhas do seu código e das cadeias de conexão.

SQL Server com autenticação Microsoft Entra (recomendado)

Este exemplo usa ActiveDirectoryDefault, que tenta múltiplas fontes de credenciais (CLI do Azure, variáveis de ambiente, identidade gerenciada) em ordem. Nenhuma senha é armazenada no código:

import mssql_python

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;Authentication=ActiveDirectoryDefault;Encrypt=yes;"
)

SQL Server com autenticação SQL

Use autenticação SQL apenas para desenvolvimento local em uma instância do SQL Server que você controle. As credenciais são incorporadas na cadeia de conexão, então mantenha-as em variáveis de ambiente ou em um .env arquivo, em vez de no código-fonte:

conn = mssql_python.connect(
    "Server=<server>;"
    "Database=<database>;"
    "UID=<login>;"
    "PWD=<password>;"
    "Encrypt=yes;"
)

SQL do Azure com autenticação Microsoft Entra

A cadeia de conexão para Banco de Dados SQL do Azure é a mesma do SQL Server. ActiveDirectoryDefaultfunciona em ambientes de desenvolvimento local, containers e hospedados no Azure sem alterações de código:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

Usar argumentos de palavras-chave

Você pode passar parâmetros de conexão como argumentos de palavras-chave em vez de ou além de uma cadeia de conexão. Argumentos de palavras-chave evitam os erros escapados do cadeia de conexão assembly. Senhas com caracteres especiais como @, ;, , {ou } não precisam de enrolamento curly-brace quando passadas como argumentos de palavra-chave:

conn = mssql_python.connect(
    server="<server>.database.windows.net",
    database="<database>",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

Compare com cadeia de conexão assembly, onde uma senha contendo @ deve ser encapsulada:

# Connection string requires escaping
conn = mssql_python.connect("Server=srv;UID=user;PWD={p@ss;word};")

# Keyword arguments - no escaping needed
conn = mssql_python.connect(server="srv", uid="user", pwd="p@ss;word")

O driver mescla argumentos de palavras-chave na cadeia de conexão após a normalização. Se um argumento de palavra-chave corresponder a um parâmetro já presente na cadeia de conexão, o argumento de palavra-chave tem precedência e substitui o valor da cadeia de conexão:

# The keyword argument database="production" overrides Database=dev in the connection string
conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;Encrypt=yes;",
    database="production",
    authentication="ActiveDirectoryDefault"
)
# Connects to "production", not "dev"

O exemplo a seguir combina uma cadeia de conexão com argumentos de palavras-chave:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

Palavras-chave de cadeia de conexão

Servidor e banco de dados

Especifique a instância e o banco de dados do SQL Server alvo para a conexão.

Authentication

Forneça credenciais para autenticação SQL ou especifique um modo de autenticação Microsoft Entra. Para opções sem senha, veja modos de autenticação Microsoft Entra.

Criptografia e segurança

Todas as conexões são usadas Encrypt=yes por padrão. Para a maioria das aplicações, o padrão é suficiente. Use strict apenas quando sua instância do SQL Server suportar TDS 8.0 e você precisar de TLS 1.3. TrustServerCertificate=yes Use apenas em ambientes de desenvolvimento com certificados autoassinados.

Alta disponibilidade e alternância em caso de falha

Essas palavras-chave se aplicam a implantações em grupos de disponibilidade Sempre Ativa. Configurado ApplicationIntent=ReadOnly para direcionar cargas de trabalho pesadas em leitura (relatórios, análises) para réplicas secundárias, reduzindo a carga no primário. Defina MultiSubnetFailover=yes quando seu grupo de disponibilidade abrange várias sub-redes.

Desempenho e rede

Os padrões funcionam para a maioria das aplicações. Aumento PacketSize (até 32767) para transferências de dados em massa. Configure KeepAlive se as conexões cruzam firewalls ou balanceadores de carga que caem em sessões TCP ociosas.

Palavras-chave reservadas

Modos de autenticação Microsoft Entra

A Authentication palavra-chave suporta os seguintes valores. Escolha o modo que combine com sua implantação:

Para configuração reprodutível de Docker, devcontainer e ambiente CI, veja Container e desenvolvimento local. Esse artigo centraliza a seleção de runtime em Python e mostra como usar imagens fixadas em resumos em ambientes compartilhados.

Exemplo: DefaultAzureCredential

ActiveDirectoryDefaultmapeia para a cadeia de identidade DefaultAzureCredential do Azure. Ele tenta primeiro o token CLI do Azure durante o desenvolvimento local, depois gerencia a identidade quando implantado no Azure:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

Exemplo: Fluxo de código de dispositivo

Use o fluxo de código do dispositivo ao rodar em ambientes sem navegador, como sessões SSH ou contêineres Docker. O driver exibe uma URL e um código para inserir em um dispositivo separado:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDeviceCode;"
    "Encrypt=yes;"
)
# Follow the prompt to authenticate at https://microsoft.com/devicelogin

Exemplo: Principal de serviço

A autenticação do principal de serviço utiliza uma identidade de aplicação registrada com um ID de cliente e um segredo. Use essa abordagem para pipelines CI/CD e serviços em segundo plano que rodam sem interação do usuário:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<client-id>;"
    "PWD=<client-secret>;"
    "Encrypt=yes;"
)

Para registrar a aplicação e conceder acesso ao banco de dados, veja Microsoft Entra service principals com SQL do Azure. Para a configuração completa em mssql-python, veja autenticação do principal de serviço.

Tempo de espera da conexão esgotado

Defina o timeout da conexão usando o timeout parâmetro. Use um timeout para evitar que sua aplicação fique travada indefinidamente quando o servidor estiver inacessível:

# 30-second connection timeout
conn = mssql_python.connect(connection_string, timeout=30)

Você também pode alterar o timeout em uma conexão existente:

conn.timeout = 60

Modo de confirmação automática

Por padrão, autocommit é False, o que requer chamadas explícitas commit() . Ative o autocommit para instruções DDL ou consultas somente leitura que não precisem de controle de transação:

# Via parameter
conn = mssql_python.connect(connection_string, autocommit=True)

# Or after connection
conn.setautocommit(True)

Atributos de conexão

Defina atributos de conexão ODBC antes que a conexão seja estabelecida usando attrs_before:

import mssql_python

conn = mssql_python.connect(
    connection_string,
    attrs_before={
        mssql_python.SQL_ATTR_LOGIN_TIMEOUT: 30,
        mssql_python.SQL_ATTR_CONNECTION_TIMEOUT: 60,
    }
)

Construção programática de cadeia de conexão

Para evitar a injeção de cadeia de conexão, não use concatenação de strings ou f-strings com entrada do usuário. Use argumentos de palavras-chave ou variáveis de ambiente em vez disso. Para mais padrões de construção, incluindo arquivos de configuração JSON/YAML, Azure Key Vault e uma classe builder, veja Build connection strings programáticamente.

import os

conn = mssql_python.connect(
    server=os.environ["DB_SERVER"],
    database=os.environ["DB_NAME"],
    authentication=os.environ.get("DB_AUTH", "ActiveDirectoryDefault"),
    encrypt="yes"
)

Validação de string de conexão

O driver valida as strings de conexão e aumenta ConnectionStringParseError para palavras-chave desconhecidas ou com erros ortográficos:

try:
    conn = mssql_python.connect("Servr=localhost;")  # Typo
except mssql_python.ConnectionStringParseError as e:
    print(f"Invalid connection string: {e}")
    # Output: Unknown keyword 'Servr'

Conteúdo relacionado

• Construir cadeias de conexão programáticamente
• Instalar mssql-python
• Autenticação do Microsoft Entra
• Agrupamento de conexões
• Gerenciamento de conexões