Início Rápido: Conectar-se com o driver pyodbc para Python

2025-06-27

Neste Início Rápido, você conecta um script Python a um banco de dados que você criou e carregou com dados de exemplo. Use o pyodbc driver do Python para se conectar ao banco de dados e executar operações básicas, como ler e gravar dados.

documentação pyodbc | código-fonte do pyodbc | pacote (PyPi)

Pré-requisitos

Python 3
- Se você ainda não possui o Python, instale o runtime do Python e o gerenciador de pacotes Índice de Pacotes do Python (PyPI) de python.org.
- Prefere não usar seu próprio ambiente? Abra como um devcontainer usando o GitHub Codespaces.
pyodbc pacote do PyPI.
Um banco de dados no SQL Server, no Banco de Dados SQL do Azure ou no Banco de Dados SQL no Fabric com o AdventureWorks2022 esquema de exemplo e uma cadeia de conexão válida.

Configurando

Siga estas etapas para configurar seu ambiente de desenvolvimento para desenvolver um aplicativo usando o pyodbc driver Python.

Observação

Esse driver usa o protocolo TDS , que está habilitado por padrão no SQL Server, no Banco de Dados SQL no Fabric e no Banco de Dados SQL do Azure. Não é necessária configuração adicional.

Instale o pacote pyodbc

Obtenha o pyodbc pacote do PyPI.

Abra um prompt de comando em um diretório vazio.
Instale o pacote pyodbc.
```
pip install pyodbc
```

Verifique os pacotes instalados

Você pode usar a ferramenta de linha de comando PyPI para verificar se os pacotes pretendidos estão instalados.

Verifique a lista de pacotes instalados com pip list.
```
pip list
```

Criar um Banco de Dados SQL

Este início rápido requer o esquema AdventureWorks2022 Lightweight , no Microsoft SQL Server, no banco de dados SQL no Fabric ou no Banco de Dados SQL do Azure.

Criar um banco de dados SQL em minutos usando o portal do Azure

Criar um novo arquivo

Crie um arquivo chamado app.py.

Adicione um módulo docstring.

"""
Connects to a SQL database using pyodbc
"""

Importar o pacote pyodbc.

from os import getenv
from dotenv import load_dotenv
from pyodbc import connect

Use a função pyodbc.connect para se conectar a um banco de dados SQL.
```
load_dotenv()
conn = connect(getenv("SQL_CONNECTION_STRING"))
```
No diretório atual, crie um novo arquivo chamado *.env.
No arquivo *.env, adicione uma entrada para sua cadeia de conexão chamada SQL_CONNECTION_STRING. Substitua o exemplo aqui pelo valor real da cadeia de conexão.
```
SQL_CONNECTION_STRING="Driver={ODBC Driver 18 for SQL Server};Server=<server_name>;Database={<database_name>};Encrypt=yes;TrustServerCertificate=no;Authentication=ActiveDirectoryInteractive"
```
Dica

A cadeia de conexão usada aqui depende em grande parte do tipo de banco de dados SQL ao qual você está se conectando. Para obter mais informações sobre cadeias de conexão e sua sintaxe, consulte a referência de sintaxe da cadeia de conexão.

Executar uma consulta

Use uma cadeia de caracteres de consulta SQL para executar uma consulta e analisar os resultados.

Crie uma variável para a cadeia de caracteres de consulta SQL.

SQL_QUERY = """
SELECT
TOP 5 c.CustomerID,
c.CompanyName,
COUNT(soh.SalesOrderID) AS OrderCount
FROM
SalesLT.Customer AS c
LEFT OUTER JOIN SalesLT.SalesOrderHeader AS soh ON c.CustomerID = soh.CustomerID
GROUP BY
c.CustomerID,
c.CompanyName
ORDER BY
OrderCount DESC;
"""

Use cursor.execute para recuperar um conjunto de resultados de uma consulta em relação ao banco de dados.
```
cursor = conn.cursor()
cursor.execute(SQL_QUERY)
```
Observação

Essencialmente, essa função aceita qualquer consulta e retorna um conjunto de resultados que pode ser iterado com o uso de cursor.fetchone().
Use cursor.fetchall com um loop foreach para obter todos os registros do banco de dados. Em seguida, imprima os registros.
```
records = cursor.fetchall()
for r in records:
    print(f"{r.CustomerID}\t{r.OrderCount}\t{r.CompanyName}")
```
Salve o app.py arquivo.

Abra um terminal e teste o aplicativo.

python app.py

Esta é a saída esperada.

29485   1       Professional Sales and Service
29531   1       Remarkable Bike Store
29546   1       Bulk Discount Store
29568   1       Coalition Bike Company
29584   1       Futuristic Bikes

Inserir uma linha como uma transação

Execute uma instrução INSERT com segurança e passe parâmetros. Passar parâmetros como valores protege seu aplicativo contra ataques de injeção de SQL .

Adicione uma importação de randrange da biblioteca random no topo de app.py.
```
from random import randrange
```
No final de app.py, adicione o código para gerar um número de produto aleatório.
```
productNumber = randrange(1000)
```
Dica

Gerar um número de produto aleatório aqui garante que você possa executar essa amostra várias vezes.

Crie uma cadeia de caracteres de instrução SQL.

SQL_STATEMENT = """
INSERT SalesLT.Product (
Name,
ProductNumber,
StandardCost,
ListPrice,
SellStartDate
) OUTPUT INSERTED.ProductID
VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP)
"""

Execute a instrução usando cursor.execute.

cursor.execute(
    SQL_STATEMENT,
    (
        f'Example Product {productNumber}',
        f'EXAMPLE-{productNumber}',
        100,
        200
    )
)

Busque a primeira coluna do resultado único usando cursor.fetchval, imprima o identificador exclusivo do resultado e confirme a operação como uma transação usando connection.commit.
```
resultId = cursor.fetchval()
print(f"Inserted Product ID : {resultId}")
conn.commit()
```
Dica

Opcionalmente, você pode usar connection.rollback para reverter a transação.
Feche o cursor e a conexão usando cursor.close e connection.close.
```
cursor.close()
conn.close()
```
Salve o app.py arquivo e teste o aplicativo novamente.
```
python app.py
```
Esta é a saída esperada.
```
Inserted Product ID : 1001
```

Próxima etapa

Visite o pyodbc repositório GitHub do driver para obter mais exemplos, e para contribuir com ideias ou relatar problemas.

driver pyodbc no GitHub

Compartilhar via