Strings de ligação para mssql-python

O driver mssql-python suporta as seguintes palavras-chave de cadeia de ligação ao ligar ao SQL Server, Base de Dados SQL do Azure, Azure SQL Managed Instance e base de dados SQL no Microsoft Fabric.

Sintaxe da cadeia de conexão

As cadeias de ligação usam pares chave-valor separados por ponto e vírgula:

keyword1=value1;keyword2=value2;...

Valores de envolvimento que contêm caracteres especiais (ponto e vírgula, sinais iguais ou colchetes enrolados) entre colchetes:

PWD={my;complex=password}

Para incluir uma coltese de fecho literal num valor, use duas chaves de fecho (}}):

PWD={password}}with}}brace}

Exemplos básicos de ligação

Os exemplos seguintes mostram como se ligar usando diferentes métodos de autenticação. Para aplicações de produção, utilize autenticação Microsoft Entra sempre que possível. Elimina palavras-passe do teu código e das cadeias de ligação.

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

Este exemplo utiliza ActiveDirectoryDefault, que tenta múltiplas fontes de credenciais (CLI do Azure, variáveis de ambiente, identidade gerida) por ordem. Não é armazenada nenhuma palavra-passe 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 numa instância do SQL Server que controle. As credenciais estão incorporadas na cadeia de ligação, por isso mantém-nas em variáveis de ambiente ou num .env ficheiro 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 ligação para Base de Dados SQL do Azure é a mesma que para SQL Server. ActiveDirectoryDefaultfunciona em desenvolvimento local, contentores e ambientes alojados 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

Pode passar parâmetros de conexão como argumentos-chave em vez de ou além de uma cadeia de ligação. Os argumentos de palavras-chave evitam as armadilhas escapatórias da cadeia de ligação assembly. Palavras-passe com caracteres especiais como @, ;, {, ou } não necessitam de enrolamento curly-brace quando passadas como argumentos de palavras-chave:

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

Compare com cadeia de ligação assembly, onde uma palavra-passe contém @ 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 funde argumentos de palavras-chave na cadeia de ligação após a normalização. Se um argumento de palavra-chave corresponder a um parâmetro já presente na cadeia de ligação, o argumento da palavra-chave tem precedência e sobrepõe-se ao valor da cadeia de ligaçã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 seguinte combina uma cadeia de ligaçã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 ligação

Servidor e base de dados

Especifique a instância e a base de dados do SQL Server alvo para a ligação.

Authentication

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

Encriptação e segurança

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

Alta disponibilidade e failover

Estas palavras-chave aplicam-se a implementações em grupos de disponibilidade Sempre Ativada. Defina ApplicationIntent=ReadOnly para encaminhar cargas de trabalho pesadas em leitura (relatórios, análises) para réplicas secundárias, reduzindo a carga na primária. Define MultiSubnetFailover=yes quando o teu 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 massivas de dados. Configura KeepAlive se as ligações atravessam firewalls ou balanceadores de carga que deixam de usar 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 corresponde à sua missã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 digest em ambientes partilhados.

Exemplo: DefaultAzureCredential

ActiveDirectoryDefaultmapeia para a cadeia de identidade DefaultAzureCredential do Azure. Tenta primeiro o token CLI do Azure durante o desenvolvimento local, depois gerir a identidade quando implementado no Azure:

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

Exemplo: Fluxo de código do dispositivo

Use o fluxo de código do dispositivo ao correr em ambientes sem navegador, como sessões SSH ou contentores Docker. O driver apresenta uma URL e um código para introduzir num 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 registada com um ID de cliente e um segredo. Use esta abordagem para pipelines CI/CD e serviços em segundo plano que correm sem interação do utilizador:

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

Para registar a aplicação e conceder-lhe acesso à base de dados, consulte Microsoft Entra service principals with SQL do Azure. Para a configuração completa em mssql-python, veja autenticação do principal de serviço.

Tempo limite de ligação

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

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

Também pode alterar o timeout de uma ligação existente:

conn.timeout = 60

Modo de confirmação automática

Por defeito, autocommit é False, o que requer chamadas explícitas commit() . Ative o autocommit para instruções DDL ou consultas apenas de leitura que não necessitem de controlo de transações:

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

# Or after connection
conn.setautocommit(True)

Atributos de ligação

Defina atributos de ligação ODBC antes de a ligação ser 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 ligação

Para evitar a injeção de cadeia de ligação, não use concatenação de strings ou f-strings com input do utilizador. Use argumentos-chave ou variáveis de ambiente em vez disso. Para mais padrões de construção, incluindo ficheiros 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 cadeias de ligação

O driver valida cadeias de ligação e aumenta ConnectionStringParseError para palavras-chave desconhecidas ou mal escritas:

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 ligação programaticamente
• Instalar mssql-python
• Autenticação do Microsoft Entra
• Pool de conexões
• Gestão de ligações