Como conectar Python ao SQL Server com pyodbc

Conectar o Python ao SQL Server é uma das tarefas mais comuns de quem trabalha com dados na plataforma Microsoft: permite ler tabelas, correr consultas e trazer os resultados diretamente para um DataFrame do pandas. A forma mais fiável de o conseguir é através da biblioteca pyodbc, que assenta no driver ODBC oficial da Microsoft. A seguir mostramos, passo a passo, como montar essa ligação do zero, com exemplos prontos a usar e os erros mais comuns a evitar.

Pré-requisitos

• Python 3.9 ou superior instalado no seu sistema.
• Acesso a uma instância de SQL Server (local, numa VM ou no Azure SQL) e as respetivas credenciais.
• O Microsoft ODBC Driver 18 for SQL Server (ou a versão mais recente) instalado no sistema operativo.
• Permissões para executar pip install no seu ambiente Python.

Passo 1: Instalar a biblioteca pyodbc

Comece por instalar o pacote no seu ambiente. Se utiliza ambientes virtuais — o que é recomendado —, ative-o primeiro e só depois execute o comando.

pip install pyodbc pandas

O pyodbc trata da comunicação com o SQL Server e o pandas vai receber os dados em formato tabular. Atenção: o driver ODBC em si não se instala por pip — é um componente do sistema operativo que deve descarregar do site da Microsoft.

Passo 2: Confirmar que o driver ODBC está disponível

Antes de ligar, confirme que o Python "vê" o driver. Este pequeno exemplo lista todos os drivers ODBC instalados na máquina.

import pyodbc

for driver in pyodbc.drivers():
    print(driver)

Na saída deve aparecer uma linha como ODBC Driver 18 for SQL Server. Se a lista sair vazia ou sem nenhum driver de SQL Server, instale-o antes de continuar — é a causa número um do erro "Data source name not found".

Passo 3: Criar a ligação ao SQL Server

A ligação é definida por uma connection string com o driver, o servidor, a base de dados e as credenciais. Guarde a password fora do código, por exemplo numa variável de ambiente, e nunca a deixe escrita no ficheiro.

import os
import pyodbc

conn_str = (
    "DRIVER={ODBC Driver 18 for SQL Server};"
    "SERVER=localhost,1433;"
    "DATABASE=Vendas;"
    "UID=leitor;"
    "PWD=" + os.environ["SQL_PWD"] + ";"
    "Encrypt=yes;"
    "TrustServerCertificate=yes;"
)

conn = pyodbc.connect(conn_str)
print(conn.getinfo(pyodbc.SQL_DBMS_NAME))

Alguns pontos importantes: no driver 18, Encrypt=yes é o valor por omissão e é uma boa prática de segurança. Use TrustServerCertificate=yes apenas em desenvolvimento, com certificados autoassinados; em produção prefira um certificado válido e TrustServerCertificate=no. Para autenticação integrada do Windows, substitua UID e PWD por Trusted_Connection=yes.

Passo 4: Executar uma consulta e ler os resultados

Com a ligação aberta, crie um cursor para correr comandos SQL. Use sempre parâmetros (o ?) em vez de concatenar valores na consulta — é o que protege a aplicação de injeção de SQL.

cursor = conn.cursor()

cursor.execute(
    "SELECT TOP 5 id, cliente, total FROM dbo.Encomendas WHERE total > ?",
    100,
)

for row in cursor.fetchall():
    print(row.id, row.cliente, row.total)

O método fetchall() devolve todas as linhas de uma vez; em tabelas grandes, percorra o cursor diretamente ou use fetchmany() para poupar memória.

Passo 5: Trazer os dados para um DataFrame pandas

Para análise, o mais prático é carregar o resultado diretamente num DataFrame. A função read_sql do pandas aceita a consulta e a ligação pyodbc.

import pandas as pd

df = pd.read_sql("SELECT * FROM dbo.Encomendas", conn)
print(df.head())
print(len(df))

conn.close()

Feche sempre a ligação no fim com conn.close(), ou abra-a dentro de um bloco with para que o Python a feche automaticamente.

Verificar o resultado

Se tudo correu bem, ao executar o script do Passo 3 vê impresso o nome do SGBD — Microsoft SQL Server — e, nos passos seguintes, as primeiras linhas da tabela no terminal. Para confirmar que os valores estão corretos, compare-os com o resultado da mesma consulta no SQL Server Management Studio ou no Azure Data Studio. Se receber o erro "Login failed for user", reveja as credenciais; se for "server was not found", confirme o nome do servidor, a porta e se a firewall permite a ligação.

Conclusão

Com poucas linhas de código, o Python passa a ler e a escrever no SQL Server, abrindo caminho para automatizar relatórios, alimentar modelos de machine learning ou construir pipelines de dados. O passo seguinte natural é parametrizar a connection string por ambiente e experimentar o SQLAlchemy, que assenta sobre o pyodbc e simplifica a escrita de DataFrames de volta para a base de dados. Qual é a consulta do seu dia a dia que gostaria de automatizar primeiro?