Conecte-se a um Microsoft SQL Server usando Python e Pyodbc

Use pyodbc para conectar uma aplicação Python ao Microsoft SQL Server por meio de ODBC. Instale o pacote Python e um driver ODBC compatível com SQL Server; depois, passe o servidor, o banco de dados, o driver e as configurações de autenticação para pyodbc.connect(). Este guia usa SQL direto. Um ORM é outra opção quando você quer representar tabelas do banco de dados como objetos Python.

Instalar pyodbc e o driver ODBC do SQL Server

Instale pyodbc no mesmo ambiente Python em que sua aplicação será executada, por exemplo, com python -m pip install pyodbc. Isso instala a interface Python, mas não o driver ODBC da Microsoft. Instale separadamente um driver ODBC para SQL Server na máquina ou no contêiner em que o programa será executado e confirme que o nome informado corresponde exatamente ao driver instalado. Um nome comum é ODBC Driver 18 for SQL Server; use o nome disponível no seu sistema.

Antes de se conectar, reúna o endereço do servidor e o nome do banco de dados. O servidor pode ser um nome de host, um endereço ou um host com o nome da instância, como db.example.net\SQLEXPRESS; implantações hospedadas também podem exigir uma porta. Talvez seu administrador precise conceder à conta acesso ao banco de dados escolhido. As informações de conexão do SQL Server não dependem do diretório de trabalho do Python, mas o driver precisa estar disponível para o gerenciador ODBC do sistema operacional.

Conectar com um driver e autenticação integrada

Em um ambiente Windows configurado para autenticação integrada, use uma string de conexão baseada em driver com Trusted_Connection=yes. Substitua os valores de driver, servidor e banco de dados pelos da sua instalação. O pequeno programa a seguir monta e exibe a string para que você possa conferir como os campos são unidos; ele não se conecta a um banco de dados.

Execute este exemplo:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

driver = "ODBC Driver 18 for SQL Server"
server = "db.example.net"
database = "Sales"
connection_string = (
    f"Driver={{{driver}}};"
    f"Server={server};"
    f"Database={database};"
    "Trusted_Connection=yes;"
)
print(connection_string)

Driver={ODBC Driver 18 for SQL Server};Server=db.example.net;Database=Sales;Trusted_Connection=yes;

Para abrir a conexão na sua aplicação, passe essa string para pyodbc.connect(connection_string). A autenticação integrada usa a identidade disponível para o processo e depende da configuração do sistema operacional, do driver e do SQL Server; ela não equivale a informar um nome de usuário e uma senha do SQL Server. Para configurar TLS, siga a política de certificados da sua organização. Os padrões de criptografia podem variar entre versões do driver, portanto, não desative as verificações de certificado apenas para fazer a conexão funcionar.

Conectar por meio de um DSN com credenciais

Um Data Source Name (DSN) é uma configuração ODBC criada no host. Ela pode armazenar configurações compartilhadas do servidor e do driver, deixando para a aplicação apenas o nome do DSN e, quando necessário, as credenciais. A string de conexão tem este formato: DSN=SalesReadOnly;UID=app_reader;PWD=<secret>;. O DSN precisa existir no mesmo ambiente e estar visível para o processo Python; um DSN configurado para um usuário interativo talvez não esteja disponível para uma conta de serviço ou um contêiner.

Forneça as credenciais por meio de um gerenciador de segredos ou de uma configuração específica do ambiente, em vez de incluí-las no controle de versão. Se o segredo contiver caracteres especiais, use as regras de aspas aceitas pelas strings de conexão ODBC ou configure a credencial separadamente; caso contrário, um ponto e vírgula poderá ser interpretado como separador de campos. Evite imprimir a string de conexão completa, pois isso pode expor a senha nos registros. Use a mesma chamada pyodbc.connect(...) com a string do DSN e escolha a autenticação integrada ou a autenticação SQL conforme a configuração do DSN e do servidor.

Executar uma consulta e fechar os recursos

Depois de se conectar, crie um cursor, execute o SQL e obtenha as linhas retornadas, seja buscando-as, seja iterando sobre elas. Use marcadores de parâmetro para valores fornecidos por usuários ou dados da aplicação. No pyodbc, ? é o marcador posicional; passar os valores separadamente mantém esses valores distintos do texto SQL. Parâmetros servem para valores de dados, não para nomes de tabelas ou colunas. Se um identificador precisar variar, escolha-o em uma lista de permissões fixa e use as aspas adequadas às regras do SQL Server.

Um fluxo típico da aplicação começa com connection = pyodbc.connect(connection_string), seguido por cursor = connection.cursor() e cursor.execute("SELECT name FROM dbo.Customers WHERE customer_id = ?", customer_id). Itere sobre cursor para processar as linhas ou chame fetchall() quando o resultado for pequeno o bastante para caber na memória. Para conjuntos de resultados grandes, processe as linhas aos poucos. A consulta pressupõe que a tabela e a coluna indicadas existam no banco de dados selecionado; substitua-as pelas do seu esquema.

Depois que connection = pyodbc.connect(connection_string) for concluída com sucesso, mantenha o trabalho com o cursor dentro de um bloco try e feche a conexão na cláusula finally: try: ... finally: connection.close(). Para limpar o cursor, use with connection.cursor() as cursor: dentro desse bloco; ao sair do contexto do cursor, ele será fechado. Um contexto de conexão do pyodbc, como with connection:, gerencia o escopo da transação: confirma a transação ao sair normalmente e a reverte quando uma exceção é propagada, mas não fecha a conexão. Você pode combinar esse contexto de transação com o contexto do cursor dentro do try e chamar connection.close() no finally. Assim, a conexão é fechada após o processamento da consulta tanto em uma saída normal quanto em uma saída excepcional, desde que tenha sido aberta com sucesso. Se você alterar dados, decida explicitamente em que ponto a transação deve ser confirmada. Esse padrão de uso exige um SQL Server, um driver e um esquema configurados; ele não foi executado como parte deste artigo.

Diagnosticar erros comuns de conexão

Se o pyodbc informar que não encontrou um driver, confira se o driver ODBC está instalado no ambiente de execução do programa e se o valor de Driver={...} corresponde ao nome registrado, incluindo espaços e a versão. Se não for possível alcançar o servidor, verifique o DNS ou a grafia do host, as configurações de porta e instância, o acesso pelo firewall e se o SQL Server aceita conexões de rede. Em geral, um tempo limite indica problemas de conectividade ou carga no servidor; aumentá-lo não corrige um destino incorreto.

Se houver falha de login, confirme qual identidade a conexão está usando. A autenticação integrada usa a identidade do processo, enquanto UID e PWD solicitam credenciais SQL; misturar essas opções pode enviar a identidade errada. Em seguida, confira o acesso ao banco de dados e o nome dele. Para erros de certificado ou criptografia, confirme com seu administrador a cadeia de certificados do servidor e as configurações de criptografia do driver, em vez de enfraquecer a verificação. Por fim, examine a string de conexão em busca de ponto e vírgula ausente, chaves sem correspondência ao redor dos nomes dos drivers, espaços acidentais nas chaves ou caracteres especiais sem escape. Mantenha os registros de diagnóstico úteis, mas oculte senhas e outros segredos.

Para obter detalhes sobre drivers e strings de conexão, consulte as orientações de conexão do pyodbc com SQL Server e a documentação oficial do pyodbc. Para ver um exemplo relacionado à leitura dos resultados de uma consulta, consulte How to Extract Elements From a Database Using fetchall() in Python. Não há um destino em português disponível para esse artigo relacionado.