Guia de início rápido: conecte-se com o driver pyodbc para Python

2025-06-20

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

Documentação pyodbc | código fonte pyodbc | Pacote (PyPi)

Pré-requisitos

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

Preparação

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 é habilitado por padrão no SQL Server, no banco de dados SQL no Fabric e no Banco de Dados SQL do Azure. Nenhuma configuração extra é necessária.

Instalar 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 uma base de dados SQL

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

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

Criar um novo ficheiro

Crie um novo arquivo chamado app.py.

Adicione um módulo docstring.

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

Importe o pacote pyodbc.

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

Use a pyodbc.connect função 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.
Dentro do *.env arquivo, 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"
```
Sugestão

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 Referência de sintaxe de 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 no banco de dados.
```
cursor = conn.cursor()
cursor.execute(SQL_QUERY)
```
Observação

Esta função essencialmente aceita qualquer consulta e retorna um conjunto de resultados, que pode ser iterado com o uso de cursor.fetchone().
Use cursor.fetchall com um foreach loop 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

Aqui está 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

Insira 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 para randrange da biblioteca random ao topo de app.py.
```
from random import randrange
```
No final de app.py, adicione código para gerar um número de produto aleatório.
```
productNumber = randrange(1000)
```
Sugestão

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

Crie uma cadeia 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
    )
)

Buscar a primeira coluna do resultado único usando cursor.fetchval, imprimir o identificador exclusivo do resultado e, em seguida, confirmar a operação como uma transação usando connection.commit.
```
resultId = cursor.fetchval()
print(f"Inserted Product ID : {resultId}")
conn.commit()
```
Sugestão

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
```
Aqui está a saída esperada.
```
Inserted Product ID : 1001
```

Próximo passo

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

driver pyodbc no GitHub

Partilhar via